Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

docs: clarify default behavior of invalidateQueries refetching #9541

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Yashkanekar wants to merge 2 commits into TanStack:main
base: main
Choose a base branch
Loading
from Yashkanekar:fix-docs-react-query-invalidateQueries
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions docs/framework/react/guides/query-invalidation.md
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ When a query is invalidated with `invalidateQueries`, two things happen:
- 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.

## Query Matching with `invalidateQueries`

When using APIs like `invalidateQueries` and `removeQueries` (and others that support partial query matching), you can match multiple queries by their prefix, or get really specific and match an exact query. For information on the types of filters you can use, please see [Query Filters](../filters.md#query-filters).
Expand Down Expand Up @@ -131,3 +133,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'`:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is partially wrong. setting type: 'all' wouldn't achieve that. It's also the default behaviour.


[//]: # 'Example6'

```tsx
queryClient.invalidateQueries({
queryKey: ['todos'],
refetchType: 'all', // or type: 'all'
})
```

[//]: # 'Example6'

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.

AltStyle によって変換されたページ (->オリジナル) /