iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
In TanStack Query, query invalidation marks matching cached queries as stale and—by default—refetches matching active queries in the background. It does not replace cached data with new server results by itself. Used after a successful update, it helps keep displayed views coherent without waiting for their usual staleTime to expire.
This guide uses the current TanStack Query API. The exact method signatures differ in older major versions, so examples below use the current object-filter form.
What query invalidation changes
Queries hold cached results associated with query keys. When an action changes server data, other cached views that depend on that data may no longer reflect the server. Calling queryClient.invalidateQueries marks selected queries stale. TanStack Query’s guide explains that the stale state overrides any configured staleTime for those queries: the application can respond to a known change rather than waiting for a freshness timer.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsInvalidation is a signal about the cache’s freshness, not an edit to the cached result. For active matching queries, the default behavior is to refetch in the background. The UI can continue displaying its current data while that request runs; invalidation does not mean rendering must wait for the new response. These are API behaviors, not a guarantee of faster rendering or a quantified smoothness improvement.
When to invalidate after an update
A common trigger is a successful mutation. For example, after saving a task, the task detail and task list may both need fresh server data. Invalidate the key or key family for the views that could now be outdated. The mutation’s success handler is a natural place to do this because the update has completed successfully.
const mutation = useMutation({
mutationFn: updateTask,
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ['tasks'] })
},
})This example assumes task-related queries use keys beginning with ['tasks'], such as ['tasks'] for a list and ['tasks', taskId] for a detail view. The prefix therefore selects both. Choose a broader or narrower filter to fit the cache relationships in your application; invalidating unrelated queries can prompt unnecessary refetch work.
How query-key matching controls scope
By default, a query-key filter can match a key and its longer descendants. Add more key parts to narrow the selection, or use exact: true when only the exact key should match.
Free tools Windows power users keep installed
One-click scans. No signup required.
| Filter | What it selects | Example use |
|---|---|---|
{ queryKey: ['tasks'] } |
Queries whose keys start with ['tasks'], including longer keys such as ['tasks', 42]. |
Refresh task lists and task details after an update that may affect both. |
{ queryKey: ['tasks', 42] } |
The more specific task-key family beginning with ['tasks', 42]. |
Target data associated with task 42 without selecting other task IDs. |
{ queryKey: ['tasks'], exact: true } |
Only the exact ['tasks'] key; longer keys with that prefix are excluded. |
Refresh only the query stored under the list key. |
Key design and invalidation scope work together: consistent key structure makes it possible to select related views deliberately. Before using a prefix, check which queries actually share it.
Rank #3
Which matching queries refetch
The current API lets you control refetching with refetchType. The default is 'active', which refetches matching active queries. A match being invalidated does not mean every matching query immediately sends a request.
refetchType: 'active': refetch matching active queries; this is the default.refetchType: 'all': select active and inactive matching queries for refetching.refetchType: 'none': mark matching queries stale without refetching them now.
// Mark matching tasks stale without refetching now
await queryClient.invalidateQueries({
queryKey: ['tasks'],
refetchType: 'none',
})The current QueryClient reference notes that disabled or static queries are not refetched by refetchQueries. Consult the API reference when relying on less common query states or filter options. The invalidation promise resolves when its refetching settles, or immediately when refetchType is 'none'.
Invalidate or update the cache directly?
Invalidation is useful when the server remains the source of truth and affected cached views should obtain current results through their normal query functions. If a mutation response already contains sufficient authoritative data, updating the cache directly can avoid waiting for another fetch. TanStack Query’s guide covers targeted invalidation alongside direct cache updates; which approach fits depends on the mutation response and the related cached views. Neither strategy is universally preferable.
Recommended Free Tools
Use the syntax for your TanStack Query version
The examples here follow the current API reference’s object-filter form, such as invalidateQueries({ queryKey: ['tasks'] }). The v3 guide documents a positional-argument form instead. Do not assume code written for one major version can be copied unchanged into another; check the documentation for the version installed in your project.
Quick Recap
Best Value
- TanStack Query Invalidation guide for current concepts and examples.
- TanStack QueryClient API reference for current filters and refetch behavior.
- TanStack Query v3 Invalidation guide for the older version’s syntax.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
