Make one configured QueryClient available throughout the app.
Application bootstrap
TanStack · Component
QueryClientProvider
QueryClientProvider supplies a QueryClient to a React component tree. It also manages the client's mount and unmount lifecycle.
How it works
QueryClientProvider places the supplied QueryClient into React context so descendant components can retrieve it with useQueryClient. Mounting and unmounting the provider also mounts or unmounts the client, connecting it to focus and online events.
Syntax
function QueryClientProvider(props: QueryClientProviderProps): Element;Parameters
| Name | Type | Description |
|---|---|---|
client | QueryClient | The QueryClient instance to provide. |
children | React.ReactNode | The components that get access to the provided QueryClient. |
context | React.Context<QueryClient | undefined> | A custom React Query context; otherwise the default context is used. |
Returns
An Element containing the supplied children, with access to the provided QueryClient through context.
Key points
- Use the provider at the application boundary to make a QueryClient available to the component tree.
- Its two core inputs are the QueryClient to expose and the descendant content that consumes it.
- Descendants wrapped by the provider are the components granted access to the supplied client.
- The returned element wraps children so hooks such as useQueryClient can read the client.
- Provider lifecycle integration lets the client respond to focus and online status changes.
Common mistakes
- The provider manages the client's mount lifecycle, so mounting and unmounting it also changes the client's event subscriptions.
- Do not start new code with contextSharing; the documentation marks this option as deprecated.
Example: Provide a QueryClient to React components
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
const queryClient = new QueryClient()
export function App() {
return (
<QueryClientProvider client={queryClient}>
<Dashboard />
</QueryClientProvider>
)
}
function Dashboard() {
return <main>Queries can access the client</main>
}Creates one client and makes it available to the descendant component tree.
When to use it
Allow descendant components to use query and mutation hooks backed by the supplied client.
Query hooks
Let the client observe focus and online events while the provider is mounted.
Focus and reconnect behavior
Interview questions
QWhat problem does QueryClientProvider solve?
QueryClientProvider supplies a QueryClient to descendant components through context. Those components can then retrieve the client with useQueryClient.
Follow-up: How does the provider affect the client's lifecycle? It calls client.mount() when mounted and client.unmount() when removed, enabling focus and online event subscriptions.
QWhat are the important QueryClientProvider props?
The required client prop is the QueryClient instance that the provider exposes. The children receive access to that instance through the provider.
Follow-up: What happens if a component is outside the provider? It cannot obtain the provider's QueryClient through the normal context-based useQueryClient mechanism.
QWhat is the component's API shape?
The React signature is function QueryClientProvider(props: QueryClientProviderProps): Element. Its props include a required client and optional children.
Follow-up: When might a custom context be relevant? The context prop lets an application use a custom React Query context instead of the default context.
Related
QueryClientuseQueryClientQueryClientProviderProps