TanStack Query

TanStack Query is a tool for one job: showing data that lives somewhere else, and keeping it up to date. To learn it from nothing, you will follow one small app from the first module to the last: a book catalogue.

• A list of books, with a search box and pages
• A page for each book, with its details
• Reviews under each book, and a form to post your own
• A reading list you can add books to and remove them from

None of the books are in the app itself. They live on another computer, and the app has to ask for them. Before any TanStack Query, this module explains how that asking works.

The app runs in a browser on someone’s laptop or phone. The books are stored on a server: a computer, somewhere on the internet, whose job is to answer questions. The app is the client: the side that asks. They talk over the network, and every question takes time to travel there and back.

Client

The program that asks for data: here, the app in the browser.

Server

A computer that keeps data and answers requests for it.

Network

The connection between them. It is slow compared with the computer itself, and it can fail.

A server can’t answer just any question. It publishes an API (application programming interface): a fixed set of requests it understands, like a menu in a restaurant. Each item on the menu is an endpoint: an address, plus what you want to do there.

Every request goes to a URL (the address you see in a browser’s bar). Its parts each have a job.

1https://api.example.com/books?search=dune&page=22└─┬──┘  └──────┬──────┘└─┬──┘└────────┬────────┘3scheme       host       path    query string

• Scheme: https means the conversation is encrypted.
• Host: which server to ask.
• Path: what you are asking about: /books, /books/42.
• Query string: optional details after ?, as name=value pairs joined by &. Here: search for "dune", and give me the second page.

The same address can mean different things depending on the request’s method (also called the HTTP verb). HTTP is the language browsers and servers speak.

The server’s answer is a response. Its first line is a three-digit status code: a quick verdict on how the request went, before any data.

The rule of thumb: 2xx went well, 4xx the client asked for something wrong, 5xx the server failed. A 4xx is usually worth showing to the person; a 5xx is often worth trying again.

After the status, a response usually has a body: the data itself. APIs nearly always send it as JSON (JavaScript Object Notation), plain text that looks like JavaScript objects and lists.

1{2  "id": 42,3  "title": "The Left Hand of Darkness",4  "author": "Ursula K. Le Guin",5  "year": 1969,6  "tags": ["science fiction", "classic"],7  "available": true8}

• { } is an object: named fields, each a "name": value pair.
• [ ] is an array: a list of values in order.
• Values are strings in double quotes, numbers, true or false, null, or more objects and arrays.

Put together, a request is a method and a URL (plus, for writes, a body), and a response is a status code and a body. Here is posting a review, as the two sides actually send it.

1POST /books/42/reviews2Content-Type: application/json3
4{ "rating": 5, "text": "Still astonishing." }5
6--- the server answers ---7
8201 Created9Content-Type: application/json10
11{ "id": 913, "rating": 5, "text": "Still astonishing." }

• The app is a client; the books live on a server; they talk over a slow, fallible network.
• An API is the set of requests a server accepts; each is a method plus a URL.
• GET reads; POST, PUT, PATCH and DELETE write.
• A response has a status code (2xx fine, 4xx client’s mistake, 5xx server’s failure) and usually a JSON body.

Code normally runs one line after another, each finishing before the next. A network request might take a second, or ten. If the browser stopped on that line, the whole page would freeze: no scrolling, no typing, no clicks.

So JavaScript does slow things asynchronously: it starts the request, carries on with other work, and comes back to it when the answer arrives. The code that runs "later" has to be written in a particular way, which is what this module is about.

Synchronous

Each step finishes before the next one starts.

Asynchronous

A step starts now and finishes later, while other work carries on.

When you start something slow, JavaScript hands you a promise at once: an object standing for a value you don’t have yet, like the ticket a coat check gives you. Later it settles, one of two ways.

Promise

An object for a value that will arrive later, or an error instead.

Fulfilled

The promise settled with a value.

Rejected

The promise settled with an error.

fetch is built into every browser. Give it a URL and it sends a GET. It returns a promise of a Response. The body arrives separately, so reading it as JSON with .json() is a second promise.

1fetch('https://api.example.com/books')2  .then((response) => response.json())3  .then((books) => {4    console.log(books.length)5  })6
7console.log('sent')

Chains of .then get hard to read. Inside a function marked async, you can write await in front of a promise: the function pauses at that line until the promise settles, while the rest of the page keeps running.

1async function getBooks() {2  const response = await fetch(3    'https://api.example.com/books'4  )5  const books = await response.json()6  return books7}8
9const promise = getBooks()

1// A pause that stands in for the network (there is none here)2const wait = (ms: number) =>3  new Promise((done) => setTimeout(done, ms))4
5async function getBooks() {6  await wait(500)7  return [{ title: 'Dune' }, { title: 'Emma' }]8}9
10const promise = getBooks()11console.log('asked; got', promise)12promise.then((books) => console.log('books:', books.length))13console.log('the page carries on')

Surprisingly, fetch only rejects when the request couldn’t be made at all (no network, say). A 404 or a 500 is still an answer, so the promise fulfils. You have to look at response.ok, which is true for 2xx codes, and fail yourself.

1async function getBook(id: number) {2  const response = await fetch(3    `https://api.example.com/books/${id}`4  )5  if (!response.ok) {6    throw new Error(`Request failed: ${response.status}`)7  }8  return response.json()9}

When an awaited promise rejects, the error is thrown at that line. Wrap the code in try { … } catch (error) { … } to handle it instead of letting it escape.

1try {2  const book = await getBook(42)3  console.log(book.title)4} catch (error) {5  console.log('Could not load the book', error)6}

fetch takes a second argument for anything other than a plain GET: the method, headers, and a body. JSON.stringify turns a JavaScript object into JSON text.

1async function postReview(bookId: number, review: NewReview) {2  const response = await fetch(3    `https://api.example.com/books/${bookId}/reviews`,4    {5      method: 'POST',6      headers: { 'Content-Type': 'application/json' },7      body: JSON.stringify(review)8    }9  )10  if (!response.ok) throw new Error('Could not post the review')11  return response.json()12}

1const response = await fetch(2  `https://api.example.com/reading-list/${bookId}`,3  { : '' }4)5if (!response.) throw new Error('Could not remove it')

There is no network on this page, so the tests replace fetch with a stand-in that answers what they choose: vi.spyOn(globalThis, 'fetch') swaps the real one for a mock, a fake that also remembers how it was called. Your code calls fetch exactly as it would for real.

1type NewReview = { stars: number; text: string }2
3async function postReview(bookId: number, review: NewReview) {4  // TODO: send it with fetch, check ok, return the JSON5  return null6}

Every read does the same three things: fetch, check ok, parse JSON. Put them in one helper. The <T> is a TypeScript type parameter: the caller says what shape of data to expect, such as getJson<Book>(…), and gets it typed.

1const API = 'https://api.example.com'2
3export async function getJson<T>(path: string): Promise<T> {4  const response = await fetch(API + path)5  if (!response.ok) {6    throw new Error(`GET ${path} failed: ${response.status}`)7  }8  return response.json()9}10
11export type Book = {12  id: number13  title: string14  author: string15}16
17export const getBook = (id: number) =>18  getJson<Book>(`/books/${id}`)

• Slow work is asynchronous: it starts now and finishes later.
• A promise stands for a future value; it fulfils with a value or rejects with an error.
• fetch returns a promise of a response; .json() is a second promise for the body.
• fetch doesn’t reject on 404 or 500: check response.ok and throw.
• A function that returns a promise of data is what TanStack Query will call a query function.

TanStack Query is used with React, a library for building screens out of components. A component is a function that returns JSX: HTML-like markup that can include JavaScript values in { }. Values passed in from outside are its props.

1type Book = { id: number; title: string; author: string }2
3function BookList({ books }: { books: Book[] }) {4  return (5    <ul>6      {books.map((book) => (7        <li key={book.id}>8          {book.title}, by {book.author}9        </li>10      ))}11    </ul>12  )13}

Component

A function that returns what part of the screen should show.

JSX

HTML-like markup inside JavaScript, with values in { }.

Props

The inputs a component is given by the one that uses it.

useState gives a component a value that survives between renders, and a function to change it. Changing it makes React call the component again (render it) and update the screen. Functions starting with use are hooks: they can only be called at the top of a component.

1function SearchBox() {2  const [search, setSearch] = useState('')3  return (4    <input5      value={search}6      onChange={(event) => setSearch(event.target.value)}7    />8  )9}

A component must only describe the screen; it can’t start a request while rendering, or it would start one on every render. useEffect runs code after React has drawn the screen, and again whenever one of its dependencies (the array at the end) has changed.

1useEffect(() => {2  document.title = `Search: ${search}`3}, [search])

Put those together and you get the classic way to load data in React: keep the data in state, fetch it in an effect, and store the answer.

1function Catalogue() {2  const [books, setBooks] = useState<Book[]>([])3
4  useEffect(() => {5    getJson<Book[]>('/books').then((data) => {6      setBooks(data)7    })8  }, [])9
10  return <BookList books={books} />11}

Until the answer arrives, the component shows an empty list, which reads as "no books at all". You need a second piece of state to say that you are still waiting.

1const [books, setBooks] = useState<Book[]>([])2const [loading, setLoading] = useState(true)3
4useEffect(() => {5  getJson<Book[]>('/books').then((data) => {6    setBooks(data)7    setLoading(false)8  })9}, [])10
11if (loading) return <p>Loading…</p>12return <BookList books={books} />

If the request rejects, nothing above ever sets loading to false: the page says "Loading…" forever. A third state holds the error.

1const [books, setBooks] = useState<Book[]>([])2const [loading, setLoading] = useState(true)3const [error, setError] = useState<Error | null>(null)4
5useEffect(() => {6  getJson<Book[]>('/books')7    .then((data) => setBooks(data))8    .catch((err) => setError(err))9    .finally(() => setLoading(false))10}, [])11
12if (loading) return <p>Loading…</p>13if (error) return <p>Could not load books.</p>14return <BookList books={books} />

With a search box, the request depends on what was typed. Put search in the dependencies and the effect runs again each time it changes. encodeURIComponent makes the text safe to put in a URL (spaces, & and so on).

1useEffect(() => {2  const q = encodeURIComponent(search)3  getJson<Book[]>(`/books?search=${q}`)4    .then((data) => setBooks(data))5}, [  ])

Three pieces of state, an effect, and three branches, for one list. Every other screen (a book’s details, its reviews, the reading list) would repeat all of it. And this version still has real bugs, which the next module uncovers.

• A component returns JSX from props and state; changing state renders it again.
• Hooks like useState and useEffect are called at the top of a component.
• Requests start in an effect, never during render.
• Doing it by hand takes data, loading and error state for every request, and forgets everything when the component goes away.

You type "du", then "dune". Two requests go out. Nothing says the server answers them in order: the "du" search might be slower. If it lands last, the screen shows results for "du" while the box says "dune". This is a race condition: the result depends on which one wins.

An effect can return a cleanup function. React calls it before running the effect again, and when the component goes away. Use it to mark the old request as unwanted.

1useEffect(() => {2  let ignore = false3  getJson<Book[]>(`/books?search=${search}`).then((data) => {4    if (!ignore) setBooks(data)5  })6  return () => {7    ignore = true8  }9}, [search])

It works, but it is one more thing to remember in every effect, and the request still runs to the end and wastes the network.

The book page shows the title in the header and the full details below. Each part fetches /books/42 in its own effect, so the same request goes out twice, and the two can even disagree if the book changed in between.

Deduplication

Noticing that a request is already running and sharing it, instead of sending another.

The moment the list arrives, it is a copy of what the server had a moment ago. Someone else posts a review; a book becomes unavailable. Your screen doesn’t know. Data that may no longer match the server is called stale.

• Leave the tab for an hour and come back: still the old list.
• Post a review: the review list on screen doesn’t include it until you reload.
• Go back to a page you saw: everything is fetched again from nothing, with a spinner.

The text in a search box belongs to the browser: only it can change it, and it is always right. The list of books belongs to the server: you only hold a copy, others can change the original, and getting it takes time and can fail.

A cache keeps copies of answers so you can reuse them. Picture a shelf where every answer is stored under a label: "books", "book 42", "reviews of book 42". Any component can read from the shelf, so two that want the same thing share one copy and one request.

Cache

A store of copies of answers, each under a label, ready to reuse.

Stale-while-revalidate

Show the copy you have now, and fetch a fresher one in the background.

TanStack Query (once called React Query) is a library that manages server state. You tell it how to fetch something and what to call it; it runs the request, stores the answer, shares it, tracks loading and errors, ignores stale answers, and refetches when the copy may be out of date.

• Hand-made fetching suffers races, duplicate requests, and stale screens that don’t update after writes.
• Server state is a copy of data someone else owns; client state belongs to the browser.
• A cache stores answers under labels and shares them: show the copy, refetch quietly.
• TanStack Query is that cache for React. You give it the fetching function; it decides when to call it.

Libraries are shared as packages and installed with npm, a tool that comes with Node.js. You run it in a terminal, a window where you type commands, from your project’s folder. It downloads the package and records it in package.json, the file listing what the project depends on.

1npm install @tanstack/react-query

Package

Code someone published for others to install and use.

npm

The tool (and registry) that installs JavaScript packages.

Terminal

A text window for running commands such as npm install.

Everything starts with a QueryClient: the object that owns the cache (the shelf from the last module) and decides when to fetch. An app makes one, once, outside any component, so it survives every render.

1import { QueryClient } from '@tanstack/react-query'2
3export const queryClient = new QueryClient()

React components get shared things from a context: a value an ancestor provides to everything below it. QueryClientProvider puts your client in context, so any component under it can use queries. Wrap the whole app in it.

1import {  } from '@tanstack/react-query'2import { queryClient } from './query-client'3
4export function Root() {5  return (6    <QueryClientProvider ={}>7      <App />8    </QueryClientProvider>9  )10}

Now the catalogue, with TanStack Query. Compare it with the effect from module 3: three pieces of state and an effect become one hook.

1import { useQuery } from '@tanstack/react-query'2
3function Catalogue() {4  const books = useQuery({5    queryKey: ['books'],6    queryFn: () => getJson<Book[]>('/books')7  })8
9  if (books.isPending) return <p>Loading…</p>10  if (books.isError) return <p>Could not load books.</p>11  return <BookList books={books.data} />12}

Query

One piece of server data in the cache, with its state: the books list, book 42.

Query key

The array naming a query. Same key, same cache entry.

Query function

Your function that fetches the data and returns a promise of it, or throws.

const [books, setBooks] = useState<Book[]>([])const [loading, setLoading] = useState(true)const [error, setError] = useState(null)useEffect(() => {  let ignore = false  getJson<Book[]>('/books')    .then((d) => !ignore && setBooks(d))    .catch((e) => !ignore && setError(e))    .finally(() => !ignore && setLoading(false))  return () => { ignore = true }}, [])

const books = useQuery({  queryKey: ['books'],  queryFn: () => getJson<Book[]>('/books')})

And for free: the answer is cached, shared with any other component using ['books'], retried on failure, and refetched when you come back to the tab.

Two components can call useQuery with the same key. They read the same cache entry, so only one request goes out, and both update together when it lands.

1function BookCount() {2  const books = useQuery({3    queryKey: ['books'],4    queryFn: () => getJson<Book[]>('/books')5  })6  return <span>{books.data?.length ?? '…'} books</span>7}

The cache is invisible, so TanStack Query ships a panel that shows it: every query, its key, its data and its state. It is only included in development builds, so it costs nothing in production.

1// npm install @tanstack/react-query-devtools2import { ReactQueryDevtools } from '@tanstack/react-query-devtools'3
4<QueryClientProvider client={queryClient}>5  <App />6  <ReactQueryDevtools initialIsOpen={false} />7</QueryClientProvider>

• Make one QueryClient, outside components, and provide it with QueryClientProvider.
• useQuery({ queryKey, queryFn }) returns isPending, isError and data.
• The key names the cache entry; the function only says how to fetch.
• Components using the same key share one entry and one request.
• The devtools show the cache while you develop.

The cache is a map from keys to queries. Two calls with equal keys get the same entry; different keys get different entries. A key is an array, and it can hold strings, numbers and plain objects.

If the query function uses a value, such as a search term or a book id, that value must be in the key. Otherwise different answers share one label, and the cache can’t tell them apart.

A key is like an effect’s dependency array, but you never list dependencies separately. When the search text changes, the key changes, and the component simply reads a different entry: from the cache if it is there, from the server if not.

1function Results({ search }: { search: string }) {2  const books = useQuery({3    queryKey: ['books', { search }],4    queryFn: () =>5      getJson<Book[]>(6        `/books?search=${encodeURIComponent(search)}`7      )8  })9  // …10}

Internally a key is turned into a string, its hash, and entries are looked up by that string. Objects in a key are hashed with their fields sorted, so their order doesn’t matter. The order of the array’s items does.

Start every key with the kind of thing it holds, then narrow it down. Later you will act on groups of queries by a key’s beginning (its prefix): "everything about books", "every book list". A consistent shape makes those groups easy to name.

TanStack Query calls your query function with one argument, the query function context. It holds the queryKey it is fetching for, and a signal (more on that next). Reading values from the key keeps the key and the request from drifting apart.

1useQuery({2  queryKey: ['books', 'detail', id],3  queryFn: ({ queryKey }) => {4    const [, , bookId] = queryKey5    return getJson<Book>(`/books/${bookId}`)6  }7})

An AbortSignal is a browser object that can tell a fetch to stop. Pass the context’s signal to fetch, and when the answer stops being wanted (the key changed, the component went away) TanStack Query aborts the request instead of letting it run to the end.

1useQuery({2  queryKey: ['books', 'list', { search }],3  queryFn: async ({  }) => {4    const q = encodeURIComponent(search)5    const response = await fetch(`${API}/books?search=${q}`, {6      7    })8    if (!response.ok) throw new Error('Search failed')9    return response.json()10  }11})

Typing keys by hand in every component invites typos. Keep them in one object of small functions, a key factory, and use it everywhere. Module 19 grows this into a full pattern.

1export const bookKeys = {2  all: ['books'] as const,3  list: (search: string) =>4    ['books', 'list', { search }] as const,5  detail: (id: number) => ['books', 'detail', id] as const,6  reviews: (id: number) =>7    ['books', 'detail', id, 'reviews'] as const8}

Keys are plain arrays, so a key factory is plain code you can test without TanStack Query. The tests use startsWith, a simple version of the prefix check TanStack Query runs when you act on a group of queries (the real one also compares objects field by field, in any order).

1const bookKeys = {2  all: ['books'] as const,3  // TODO: give each key its full shape4  lists: () => ['books'] as const,5  list: (search: string) => ['books'] as const,6  detail: (id: number) => ['books'] as const,7  reviews: (id: number) => ['books'] as const8}

• Equal keys share an entry; keys are compared by value, objects with sorted fields.
• Every value the query function uses goes in the key.
• Order keys general to specific so prefixes name useful groups.
• The query function receives { queryKey, signal }; pass signal to fetch to cancel unwanted requests.
• Keep keys in one key factory.

A query result’s status is about the data: do we have any? It is one of three values, each with a matching shortcut.

The second question is separate: is the query function running right now? That is fetchStatus. A query can have data and be fetching (a background refresh), or have no data and not be fetching (it is waiting for something).

isLoading is isPending && isFetching: no data yet and a request running. It is the right flag for a first-load spinner. isPending alone is also true for a query that is waiting to start (module 9 shows queries you switch off).

1function Catalogue() {2  const books = useQuery({3    queryKey: ['books'],4    queryFn: () => getJson<Book[]>('/books')5  })6
7  if (books.isPending) return <Spinner />8  if (books.isError) {9    return <p>Could not load books: {books.error.message}</p>10  }11  return (12    <>13      {books.isFetching && <small>Updating…</small>}14      <BookList books={books.data} />15    </>16  )17}

In version 5, error is typed as Error by default, so error.message is safe. A good rule: check isPending, then isError, then use data.

TanStack Query knows nothing about HTTP. If your function returns, the query succeeded, whatever it returned. Since fetch doesn’t reject on a 404 or 500 (module 2), the response.ok check is what turns them into query errors.

A query function is plain code: TanStack Query calls it with a context ({ queryKey, signal, … }) and reads the promise it returns. So you can test it alone, with fetch replaced by a mock, as here.

1type Entry = { bookId: number; read: boolean }2const API = 'https://api.example.com'3
4async function getReadingList({ signal }: { signal: AbortSignal }) {5  const response = await fetch(`${API}/reading-list`, { signal })6  // TODO: a failed answer must fail the query7  return (await response.json()) as Entry[]8}

Networks fail for a moment all the time. So when a query function throws in the browser, TanStack Query waits and tries again, up to 3 more times, waiting longer each time (about 1, 2, then 4 seconds, never more than 30). This growing wait is called exponential backoff. Only after the last try does the query become error.

• While retrying, status stays pending (or success, if it had data); failureCount counts the failed tries and failureReason holds the latest error.
• retry: false turns retries off; retry: 1 allows one; retry: (count, error) => … decides per error.
• retryDelay changes the wait between tries.
• On the server (module 17), retries are off by default.

A 404 will be a 404 on every try. Give your errors the status code, then let retry skip client errors (4xx) and retry the rest a few times.

1export class HttpError extends Error {2  constructor(public status: number, message: string) {3    super(message)4  }5}6
7// inside getJson:8if (!response.ok) {9  throw new HttpError(response.status, `GET ${path} failed`)10}

1const queryClient = new QueryClient({2  defaultOptions: {3    queries: {4      : (failureCount, error) => {5        if (error instanceof HttpError && error.status < 500) {6          return 7        }8        return failureCount < 9      }10    }11  }12})

If a background refetch fails, status becomes error, but data still holds the last good answer. Throwing away a perfectly good list because a refresh failed would be worse than showing it.

• status (pending, error, success) is about data; fetchStatus (fetching, paused, idle) is about requests.
• isLoading is isPending && isFetching: the first load only.
• A query fails only if its function throws, so check response.ok.
• Failures retry 3 times with exponential backoff; skip retries for 4xx with a retry function.
• A failed refetch keeps the previous data.

When an answer arrives it is fresh: TanStack Query trusts it and won’t fetch it again. After staleTime milliseconds it becomes stale: still shown, but worth checking. The default staleTime is 0, so data is stale the moment it arrives.

Stale data isn’t refetched constantly. It is refetched when something suggests the person is looking again. Each trigger can be turned off per query.

Mount means a component appearing on screen; unmount means it going away. The refetch is in the background: the stale data stays on screen until the new answer replaces it.

Book details hardly ever change. Setting staleTime means "trust this for that long": while fresh, mounts and focus don’t refetch, and components share the data with no requests.

1useQuery({2  queryKey: ['books', 'detail', id],3  queryFn: () => getBook(id),4  staleTime: 5 * 60 * 1000 // five minutes5})

Inside TanStack Query, freshness is a small calculation. A query with no data yet is stale. Otherwise it stays fresh until staleTime milliseconds have passed since dataUpdatedAt, the moment its data arrived. Write that rule yourself.

1type QueryState = { data: unknown; dataUpdatedAt: number }2
3function isStale(4  state: QueryState, staleTime: number, now: number5): boolean {6  // TODO: no data, or older than staleTime7  return false8}

When the last component using a query unmounts, the query becomes inactive. It stays in the cache in case you come back, for gcTime (garbage collection time, 5 minutes by default). Then it is deleted. Garbage collection means freeing memory nobody uses.

Options on useQuery apply to that call. Defaults for every query go on the client. A query’s own options win over the defaults.

1export const queryClient = new QueryClient({2  defaultOptions: {3    queries: {4      staleTime: 30 * 1000,5      refetchOnWindowFocus: true6    }7  }8})

Polling means fetching on a timer. For data that changes on its own, such as how many copies of a book are left, refetchInterval refetches every so many milliseconds, fresh or stale, but only while the tab is visible unless you also set refetchIntervalInBackground: true.

1const stock = useQuery({2  queryKey: ['books', 'detail', id, 'stock'],3  queryFn: () => getJson<Stock>(`/books/${id}/stock`),4  refetchInterval: 10_0005})6
7<button onClick={() => stock.refetch()}>Check now</button>

1useQuery({2  queryKey: ['genres'],3  queryFn: getGenres,4  : 5})

The devtools mark each query with its state: fresh, fetching, paused, stale or inactive, plus how many components observe it (use it). Watching one query move through those states makes this module stick.

• Data is fresh for staleTime (default 0), then stale.
• Stale queries refetch in the background on mount, window focus and reconnect; refetchInterval refetches on a timer, fresh or not.
• Unused queries are inactive, kept for gcTime (default 5 minutes), then removed.
• Raise staleTime to cut requests; set defaults on the client and override per query.

Call useQuery twice and both requests start in the same render. They run in parallel (at the same time), so the page waits for the slower one, not for the two added up.

1function BookPage({ id }: { id: number }) {2  const book = useQuery({3    queryKey: ['books', 'detail', id],4    queryFn: () => getBook(id)5  })6  const reviews = useQuery({7    queryKey: ['books', 'detail', id, 'reviews'],8    queryFn: () => getReviews(id)9  })10  // book and reviews load at the same time11}

Hooks can’t be called in a loop, because React needs the same hooks in the same order on every render. When the number of queries depends on data, such as one query per book on your reading list, useQueries takes an array of query options.

1function ReadingListCovers({ ids }: { ids: number[] }) {2  const books = useQueries({3    queries: ids.map((id) => ({4      queryKey: ['books', 'detail', id],5      queryFn: () => getBook(id)6    })),7    combine: (results) => ({8      books: results.map((r) => r.data).filter(Boolean),9      pending: results.some((r) => r.isPending)10    })11  })12  // books.books, books.pending13}

Sometimes a query needs something you don’t have yet. enabled switches a query on or off: while it is false, the query doesn’t fetch, its status is pending and its fetchStatus is idle. A query that waits for another is a dependent query.

1const book = useQuery({2  queryKey: ['books', 'detail', id],3  queryFn: () => getBook(id)4})5
6const authorId = book.data?.authorId7
8const author = useQuery({9  queryKey: ['authors', authorId],10  queryFn: () => getAuthor(authorId!),11  enabled: authorId !== undefined12})

Instead of enabled plus a !, you can pass skipToken as the query function when an input is missing. TypeScript then knows the id is defined in the other branch, without forcing it.

1import { useQuery,  } from '@tanstack/react-query'2
3const author = useQuery({4  queryKey: ['authors', authorId],5  queryFn:6    authorId === undefined7      ? 8      : () => getAuthor()9})

select is a function from the cached data to what this component wants. The cache keeps the full answer; each component can pick its own view. The component only renders again when its selected value changes.

1function ReadingListCount() {2  const count = useQuery({3    queryKey: ['reading-list'],4    queryFn: getReadingList,5    select: (list) => list.length6  })7  return <span>{count.data ?? 0}</span>8}

Change the search and the key changes, so the new entry has no data: the list vanishes behind a spinner on every keystroke. placeholderData: keepPreviousData keeps showing the last results until the new ones arrive, and sets isPlaceholderData so you can dim them.

1import { keepPreviousData, useQuery } from '@tanstack/react-query'2
3const books = useQuery({4  queryKey: ['books', 'list', { search }],5  queryFn: () => searchBooks(search),6  placeholderData: keepPreviousData7})8
9<div style={{ opacity: books.isPlaceholderData ? 0.5 : 1 }}>10  <BookList books={books.data ?? []} />11</div>

The search results already hold each book’s title and author. When you open a book, you can start its details query with that copy. initialData is put in the cache as real data, so treat it like a real answer: initialDataUpdatedAt says how old it is, so freshness still works.

A waterfall is requests running one after another when they could have run together. Dependent queries are a necessary waterfall. An accidental one comes from a child that only mounts, and so only fetches, once its parent’s query has finished.

• Several useQuery calls run in parallel; useQueries handles a dynamic list, and combine merges results.
• enabled: false or skipToken holds a query back; that is how dependent queries wait.
• select gives each component its own view and fewer renders.
• placeholderData shows something without caching it; initialData is cached as real data.
• Watch for accidental waterfalls caused by children mounting late.

A mutation is a request that changes something on the server: posting a review, adding a book to your reading list. It differs from a query in three ways.