Coordinate cache operations
A button or event handler needs to invalidate, refetch, or update cached queries.
TanStack · Hook
useQueryClient
useQueryClient returns the current React QueryClient. It uses the nearest QueryClientProvider by default, or a supplied QueryClient when one is passed.
How it works
In React, useQueryClient retrieves a QueryClient from the nearest QueryClientProvider unless a client is supplied explicitly. The returned client exposes query and mutation cache operations, such as invalidating queries. Calling the hook without an explicit client requires a provider in the component tree.
Syntax
function useQueryClient(queryClient?: QueryClient): QueryClient;Parameters
| Name | Type | Description |
|---|---|---|
queryClient | QueryClient | Optional custom client. If omitted, the client from the nearest QueryClientProvider context is used. |
Returns
The current QueryClient instance.
Key points
- The hook gives a component access to the active QueryClient.
- Its signature accepts an optional QueryClient and returns a QueryClient.
- Pass a client when the component should target a custom cache.
- Without an argument, resolution starts with the nearest provider context.
- The return value is the resolved current client, not query data or a query result.
Common mistakes
- Calling the hook without an explicit QueryClient requires a QueryClientProvider; otherwise it throws.
Example: Invalidate posts with the current client
import { QueryClient, QueryClientProvider, useQueryClient } from '@tanstack/react-query'
const client = new QueryClient()
function RefreshPosts() {
const queryClient = useQueryClient()
return (
<button onClick={() => queryClient.invalidateQueries({ queryKey: ['posts'] })}>
Refresh posts
</button>
)
}
export default function App() {
return (
<QueryClientProvider client={client}>
<RefreshPosts />
</QueryClientProvider>
)
}The component obtains the provider's QueryClient and uses it to invalidate queries whose key begins with posts.
When to use it
Target a custom client
A subtree must use a specifically selected QueryClient rather than the nearest default.
Reuse the provider client
Component logic needs access to the shared query cache without constructing another client.
Interview questions
QWhat does useQueryClient return, and where does it get the client?
It returns the current QueryClient instance. With no argument, the hook obtains the client from the nearest QueryClientProvider; passing a QueryClient lets the component use that specific client.
Follow-up: What happens if neither an explicit client nor a provider is available? The hook throws because it cannot resolve a current QueryClient.
QWhen would you pass a QueryClient to useQueryClient?
The optional argument is a QueryClient. It is useful when the component must operate on a custom client; otherwise, the nearest provider supplies the client.
Follow-up: Why might an application use more than one client? Separate clients can isolate caches, but each component must resolve the intended client rather than accidentally using the nearest default.
QHow can the returned client be used in a component?
The result can call QueryClient methods such as invalidateQueries. This lets event handlers or other component logic coordinate cached data without creating another client instance.
Follow-up: How would you refresh only a subset of cached data? Call invalidateQueries with a matching queryKey filter, as in { queryKey: ['posts'] }.
Related
QueryClientQueryClientProviderinvalidateQueriesuseQuery