Start data loading before Suspense
A page renders a Suspense-wrapped child that reads data with useSuspenseQuery.
TanStack · Hook
usePrefetchQuery
usePrefetchQuery starts a query during render so a descendant behind Suspense can use the data without initiating the first fetch itself. It returns void and skips work when the query already has cached state.
How it works
usePrefetchQuery starts a query from render so data can be available before a descendant using useSuspenseQuery renders. It accepts the same query options as queryClient.query, requires a queryKey and usually a queryFn, and optionally accepts a custom QueryClient. It has no result value.
Syntax
function usePrefetchQuery<TQueryFnData, TError, TData, TQueryData, TQueryKey>(options: UsePrefetchQueryOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>, queryClient?: QueryClient): void;Parameters
| Name | Type | Description |
|---|---|---|
options | UsePrefetchQueryOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey> | Options for the query; these are the options accepted by queryClient.query. queryKey is required, and queryFn is required unless a default query function exists. |
queryClient | QueryClient | undefined | Optional custom QueryClient. If omitted, the client from the nearest context is used. |
Returns
void; the hook does not return anything.
Key points
- The hook's return type is void; it starts work rather than exposing query data or status.
- Place it in the component that renders before the Suspense boundary to reduce the time before descendant data is available.
- Its options mirror queryClient.query, allowing query identity and query execution behavior to be configured in one object.
- Every prefetch must identify the cached query with a queryKey.
- The optional second parameter lets the caller override the client supplied by the nearest context.
- Repeated render-time calls are designed to be inexpensive when the query already has cached or in-flight state.
Common mistakes
- A query function is needed unless the QueryClient provides a default query function.
- Existing cached, pending, or error state prevents another prefetch, so the hook does not force a refetch.
Example: Prefetch before Suspense
import { Suspense } from 'react'
import { usePrefetchQuery } from '@tanstack/react-query'
async function fetchPosts() {
const response = await fetch('/api/posts')
if (!response.ok) throw new Error('Request failed')
return response.json() as Promise<{ id: number; title: string }[]>
}
function App() {
usePrefetchQuery({
queryKey: ['posts'],
queryFn: fetchPosts,
})
return (
<Suspense fallback={<p>Loading posts...</p>}>
<Posts />
</Suspense>
)
}
function Posts() {
return <div>Posts render here</div>
}Call the hook during render before a Suspense boundary containing the component that will consume the prefetched query.
When to use it
Warm the query cache
A component knows the next query key and wants to populate the cache ahead of a descendant render.
Prefetch through a custom client
An application has more than one QueryClient and needs this prefetch to target a specific one.
Interview questions
QWhat is usePrefetchQuery used for?
It initiates prefetching during render and returns void. Its intended placement is immediately before a Suspense boundary whose descendant uses useSuspenseQuery.
Follow-up: What happens when the query already has state? The prefetch is skipped, including when that state is pending or is an error from an earlier attempt.
QWhat arguments does the hook accept?
The options argument contains everything accepted by queryClient.query. The queryKey is mandatory, and queryFn is mandatory unless a default query function is configured.
Follow-up: How can a different client be selected? Pass a QueryClient as the optional second argument; otherwise the nearest context client is used.
QWhat does usePrefetchQuery return?
It returns nothing, so it is used for its prefetch side effect rather than for reading query data. A separate query hook reads the result after the prefetch has started or completed.
Follow-up: Why is calling it on every render acceptable? Cached or in-flight state causes the prefetch to be skipped instead of refetching that query.
Related
useSuspenseQueryusePrefetchInfiniteQueryqueryClient.queryQueryClientUsePrefetchQueryOptions