useQuery

TanStack

Fetching data manually is painful. There has to be a better way.

The Manual Way

Three useState hooks, a useEffect, error handling, and no caching. Every time you navigate back, it re-fetches from scratch.

PAINFUL3 useState + useEffect + manual error handling

The Fix: useQuery

One hook that handles loading, errors, caching, and background refetching. The same data, but smarter.

ELEGANTStaleFetching

One hook. Auto caching, loading states, error handling, and background refetching — all built in.

query-fetch.tsx

const { data, isPending, isError, error, refetch } = useQuery({
  queryKey: ["post", 1],
  queryFn: () =>
    fetch("https://jsonplaceholder.typicode.com/posts/1")
      .then(res => res.json()),
});

// That's it! Loading, error, caching, refetching — all handled.
// Navigate away and come back? Data is cached. Instant.

Before vs After

Manual fetch

3 useState + useEffect boilerplate
No caching — re-fetches every mount
Refetch = copy-paste the fetch logic

useQuery

1 hook — loading, error, data built in
Automatic caching + background refetch
Refetch, retry, stale time — all configurable

useQuery replaces the fetch-loading-error dance with one declarative hook call.

Playground

useQuery does more than basic fetching — query keys, caching, and automatic polling. Try these examples.

📋Post ViewerBasic Query

Loading posts...

post-viewer.tsx

const { data: posts, isPending } = useQuery({
  queryKey: ["posts"],
  queryFn: () =>
    fetch("https://jsonplaceholder.typicode.com/posts?_limit=5")
      .then(res => res.json()),
});

// Click a post → new query with different key
const { data: detail } = useQuery({
  queryKey: ["post", selectedId],
  queryFn: () => fetch(`/posts/${selectedId}`).then(r => r.json()),
  enabled: !!selectedId,  // only fetch when ID is set
});

👤User SelectorDynamic Keys

Select a user — previously fetched users load instantly from cache!

Loading user...

Query key: ["user", 1]

user-selector.tsx

const [userId, setUserId] = useState(1);

const { data: user, isPending, isFetching } = useQuery({
  queryKey: ["user", userId],  // Different key per user!
  queryFn: () =>
    fetch(`https://jsonplaceholder.typicode.com/users/${userId}`)
      .then(res => res.json()),
});

// Switch to user 2 → new query key → fetch
// Switch BACK to user 1 → cached! Instant.

🔄Auto-RefreshPolling

Toggle polling on — the data refreshes automatically every 3 seconds.

—

Last updated: —

PollingOFF

auto-refresh.tsx

const [polling, setPolling] = useState(false);

const { data } = useQuery({
  queryKey: ["time"],
  queryFn: () => ({
    time: new Date().toLocaleTimeString(),
    timestamp: Date.now(),
  }),
  refetchInterval: polling ? 3000 : false,
  // When enabled: auto-refetch every 3 seconds!
});

📄Paginated PostsPagination

Each page is a separate cache entry. Navigate back to a visited page — it loads instantly from cache.

Loading posts...

Page 1 of 20

Fetching...

paginated-posts.tsx

const [page, setPage] = useState(1);

const { data, isPlaceholderData, isFetching } = useQuery({
  queryKey: ["posts", "paginated", page],
  queryFn: () =>
    fetch(`https://jsonplaceholder.typicode.com/posts?_page=${page}&_limit=5`)
      .then(res => res.json()),
  placeholderData: keepPreviousData,
  // Keeps the old page visible while the new page loads
  // Each page number = unique cache entry
});

These are the patterns that trip up developers most often. Switch between Wrong and Fixed to compare the code side by side.

Syncing query data to local state

Copying data from useQuery into useState via useEffect

Don't do this

profile.tsx

function UserProfile({ userId }) {
  const { data } = useQuery({
    queryKey: ["user", userId],
    queryFn: () => fetchUser(userId),
  });
  const [user, setUser] = useState(null);

  // Shadow copy — goes stale on background refetch!
  useEffect(() => {
    if (data) setUser(data);
  }, [data]);

  return <div>{user?.name}</div>;
}

You now have two sources of truth. The local state freezes while the query cache gets updated by background refetches. Use the data from useQuery directly. If you need a derived value, use the select option or useMemo — never copy to useState.

Inconsistent or scattered query keys

Different components using different key shapes for the same resource

Don't do this

queries.ts

// In ComponentA:
useQuery({ queryKey: ["user", id], queryFn: () => fetchUser(id) });

// In ComponentB (typo!):
useQuery({ queryKey: ["users", id], queryFn: () => fetchUser(id) });

// Invalidation misses ComponentA:
queryClient.invalidateQueries({ queryKey: ["users"] });

TanStack Query uses query keys as cache identifiers. Inconsistent keys create duplicate cache entries, cause misses on prefetched data, and make invalidation unreliable. Centralize your keys in a query key factory so every component references the same structure.

Not handling loading and error states

Accessing data without guarding for pending or error states

Don't do this

todos.tsx

function Todos() {
  const { data } = useQuery({
    queryKey: ["todos"],
    queryFn: fetchTodos,
  });

  // Crashes on first render: data is undefined
  return <ul>{data.map(t => <li key={t.id}>{t.title}</li>)}</ul>;
}

useQuery returns a state machine. On the first render, data is undefined and isPending is true. Accessing data.map without guarding causes a runtime crash. Always check isPending first, then isError, then render with data.

The Fix: useQuery

One hook that handles loading, errors, caching, and background refetching. The same data, but smarter.

ELEGANTStaleFetching

One hook. Auto caching, loading states, error handling, and background refetching — all built in.

query-fetch.tsx

const { data, isPending, isError, error, refetch } = useQuery({
  queryKey: ["post", 1],
  queryFn: () =>
    fetch("https://jsonplaceholder.typicode.com/posts/1")
      .then(res => res.json()),
});

// That's it! Loading, error, caching, refetching — all handled.
// Navigate away and come back? Data is cached. Instant.

Before vs After

Manual fetch

3 useState + useEffect boilerplate
No caching — re-fetches every mount
Refetch = copy-paste the fetch logic

useQuery

1 hook — loading, error, data built in
Automatic caching + background refetch
Refetch, retry, stale time — all configurable

useQuery replaces the fetch-loading-error dance with one declarative hook call.

const { data: posts, isPending } = useQuery({ queryKey: ["posts"], queryFn: () => fetch("https://jsonplaceholder.typicode.com/posts?_limit=5") .then(res => res.json()), }); // Click a post → new query with different key const { data: detail } = useQuery({ queryKey: ["post", selectedId], queryFn: () => fetch(`/posts/${selectedId}`).then(r => r.json()), enabled: !!selectedId, // only fetch when ID is set });

const [userId, setUserId] = useState(1); const { data: user, isPending, isFetching } = useQuery({ queryKey: ["user", userId], // Different key per user! queryFn: () => fetch(`https://jsonplaceholder.typicode.com/users/${userId}`) .then(res => res.json()), }); // Switch to user 2 → new query key → fetch // Switch BACK to user 1 → cached! Instant.

const [polling, setPolling] = useState(false); const { data } = useQuery({ queryKey: ["time"], queryFn: () => ({ time: new Date().toLocaleTimeString(), timestamp: Date.now(), }), refetchInterval: polling ? 3000 : false, // When enabled: auto-refetch every 3 seconds! });

const [page, setPage] = useState(1); const { data, isPlaceholderData, isFetching } = useQuery({ queryKey: ["posts", "paginated", page], queryFn: () => fetch(`https://jsonplaceholder.typicode.com/posts?_page=${page}&_limit=5`) .then(res => res.json()), placeholderData: keepPreviousData, // Keeps the old page visible while the new page loads // Each page number = unique cache entry });

function UserProfile({ userId }) { const { data } = useQuery({ queryKey: ["user", userId], queryFn: () => fetchUser(userId), }); const [user, setUser] = useState(null); // Shadow copy — goes stale on background refetch! useEffect(() => { if (data) setUser(data); }, [data]); return <div>{user?.name}</div>; }

// In ComponentA: useQuery({ queryKey: ["user", id], queryFn: () => fetchUser(id) }); // In ComponentB (typo!): useQuery({ queryKey: ["users", id], queryFn: () => fetchUser(id) }); // Invalidation misses ComponentA: queryClient.invalidateQueries({ queryKey: ["users"] });

function Todos() { const { data } = useQuery({ queryKey: ["todos"], queryFn: fetchTodos, }); // Crashes on first render: data is undefined return <ul>{data.map(t => <li key={t.id}>{t.title}</li>)}</ul>; }

useQuery

The Manual Way

The Fix: useQuery

Before vs After

Playground

Common Mistakes

useQuery

The Manual Way

The Fix: useQuery

Before vs After

Playground

Common Mistakes