docs: clarify default behavior of invalidateQueries refetching #9541
Conversation
…ching Update documentation to explain that by default invalidateQueries only refetches active queries, while inactive queries are marked stale but not immediately refetched. Add guidance on using type/refetchType 'all' option to refetch all queries (active + inactive) to avoid confusion.
github-actions
bot
added
the
documentation
| - It is marked as stale. This stale state overrides any `staleTime` configurations being used in `useQuery` or related hooks | ||
| - If the query is currently being rendered via `useQuery` or related hooks, it will also be refetched in the background | ||
|
|
||
| > **Important:** By default, `invalidateQueries` will immediately refetch *only active queries*—those currently used by mounted components. Inactive queries (cached but not in use) are marked as stale but will not be refetched until they become active again (e.g., when a component utilizing the query mounts). This means that calling `invalidateQueries` without additional options does *not* guarantee all matching queries are refetched immediately. | ||
|
|
There was a problem hiding this comment.
this is pretty much the same as the two points above are also saying. The second one only says “is currently being rendered via useQuery or related hooks”, maybe this could be re-worded to “active queries”, and then explained what an active query is.
| @@ -131,3 +134,20 @@ const todoListQuery = useQuery({ | |||
| ``` | |||
|
|
|||
| [//]: # 'Example5' | |||
|
|
|||
| By default, `invalidateQueries` only refetches active queries. If you want to refetch **all matching queries**, including those currently inactive in the cache, you need to explicitly set the `refetchType` (or `type`) option to `'all'`: | |||
There was a problem hiding this comment.
this is partially wrong. setting type: 'all' wouldn't achieve that. It's also the default behaviour.
|
|
||
| This forces every matching query—active or inactive—to be refetched immediately. | ||
|
|
||
| > 🧠 **Note:** The default behavior (`refetchType: 'active'`) helps avoid unnecessary network requests. But if you're triggering an invalidation after a mutation that affects *all clients or views*, make sure to use `refetchType: 'all'` to keep all query caches up to date. |
There was a problem hiding this comment.
I don’t understand that sentence - what is “all clients or views” referring to? Imo there’s really no need to set refetchType: 'all', as it will likely lead to overfetching. It's something we have documented in the API docs, but I don’t think we need to emphasize on this with a guide.
|
View your CI Pipeline Execution ↗ for commit 4ee626c
☁️ Nx Cloud last updated this comment at |
This PR updates the documentation for the invalidateQueries method in React Query to clarify the default behavior of query invalidation and refetching.
-It explains that by default, only active queries are immediately refetched.
-Inactive queries are marked stale but not automatically refetched until they become active again.
-It adds instructions on how to force invalidation and refetching of all queries (both active and inactive) by using the type: 'all' or refetchType: 'all' option.
closes #9531