Chapter 10: Queries

Core Idea

A query is a declarative subscription to async data identified by a unique queryKey; useQuery returns a result object whose status/boolean flags tell you exactly what to render, and a separate fetchStatus tells you whether the queryFn is actually running right now.

Key Concepts

• Minimum call shape: useQuery({ queryKey, queryFn }) — a unique key plus a function returning a Promise that resolves data or throws.
• status (about the data): 'pending' (no data yet) → 'error' (threw) → 'success' (data available). Mirrored as isPending/isError/isSuccess booleans.
• fetchStatus (about the queryFn, independent of status): 'fetching' (in flight), 'paused' (wants to fetch, blocked — see Network Mode), 'idle' (not doing anything). A query can be pending + paused simultaneously (first mount, no network) — checking isPending alone is not enough to safely show a spinner in that case.
• Rule of thumb: status answers "do we have data?"; fetchStatus answers "is the fetcher running?" — they combine independently (e.g. success + fetching during a background refetch).
• Reads only: queries are for GET-shaped Promise-returning operations; use useMutation for anything that modifies server data.

Code Examples

function Todos() {
  const { isPending, isError, data, error } = useQuery({
    queryKey: ['todos'],
    queryFn: fetchTodoList,
  })

  if (isPending) return <span>Loading...</span>
  if (isError) return <span>Error: {error.message}</span>
  // TypeScript narrows `data` to defined here
  return <ul>{data.map((todo) => <li key={todo.id}>{todo.title}</li>)}</ul>
}

• What it demonstrates: the standard pending → error → success guard sequence; checking isPending then isError narrows data to non-undefined for TypeScript without a manual assertion.

Key Takeaways

1. Check isPending, then isError, then treat data as available — this order is what gives you free TypeScript narrowing.
2. Don't conflate status and fetchStatus — a pending query can be paused (offline) rather than actually fetching; isFetching is the flag for "actually in flight."
3. status/isPending etc. and the raw status string are interchangeable — pick one style and stay consistent within a codebase.

Connects To

• Network Mode: what drives fetchStatus: 'paused'.
• Query Keys: the unique identifier every query is built on.
• Query Functions: the contract a queryFn must satisfy.