docs(react): clarify staleTime 'static' vs Infinity with 'always' triggers by Zelys-DFKH · Pull Request #10354 · TanStack/query

Zelys-DFKH · 2026-03-29T21:02:37Z

Summary

staleTime: 'static' is mentioned in important-defaults.md and the useQuery reference but the distinction from Infinity is never explained
The difference matters in practice: Infinity still allows refetchOnMount/WindowFocus/Reconnect: "always" to fire; 'static' blocks those too
Adds a blockquote after the 'static' bullet explaining the behavioral difference, when to reach for each, and that resetQueries() is the escape hatch

Checklist

I have followed the steps in the Contributing guide
This change is docs-only (no release needed)

Summary by CodeRabbit

Documentation
- Clarified differences between staleTime: Infinity and staleTime: 'static': both stop staleness-based refetches, but 'static' prevents manual invalidation and blocks "always" refetch options (mount/window focus/reconnect). Added guidance on when to use truly immutable data vs. cases needing manual invalidation.

…ggers

nx-cloud · 2026-03-29T21:03:00Z

View your CI Pipeline Execution ↗ for commit b2e57fc

Command	Status	Duration	Result
`nx run-many --target=build --exclude=examples/*...`	✅ Succeeded	<1s	View ↗
`nx affected --targets=test:sherif,test:knip,tes...`	✅ Succeeded	20s	View ↗

☁️ Nx Cloud last updated this comment at 2026-03-30 16:32:11 UTC

coderabbitai · 2026-03-29T21:03:30Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6c27e054-da12-4533-b863-9a2e7107ca1d

📥 Commits

Reviewing files that changed from the base of the PR and between f4476da and b2e57fc.

📒 Files selected for processing (1)

docs/framework/react/guides/important-defaults.md

🚧 Files skipped from review as they are similar to previous changes (1)

docs/framework/react/guides/important-defaults.md

📝 Walkthrough

Walkthrough

Added a documentation advisory clarifying the behavioral difference between staleTime: Infinity and staleTime: 'static': both prevent staleness-driven refetches, but 'static' blocks invalidation and "always" refetch options, whereas Infinity still allows manual invalidation to trigger refetches.

Changes

Cohort / File(s)	Summary
Documentation Update `docs/framework/react/guides/important-defaults.md`	Added advisory clarifying that `staleTime: 'static'` is stricter than `staleTime: Infinity`: `'static'` prevents staleness-based refetches and blocks `"always"` refetch options plus ignores `queryClient.invalidateQueries()`, while `Infinity` prevents staleness-based refetches but can still be invalidated manually. Provided guidance for use cases.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Poem

🐰 I hopped through docs to leave a trace,
Of frozen queries in a quiet place,
'static' holds fast, a steadfast art,
Infinity yields when nudged apart,
A rabbit's note to play its part. 🥕

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: clarifying the distinction between staleTime 'static' and Infinity with 'always' triggers.
Description check	✅ Passed	The description covers the motivation, key behavioral differences, and implementation details. The checklist is properly filled out indicating docs-only change with no release impact.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

pkg-pr-new · 2026-03-29T21:04:06Z

More templates

@tanstack/angular-query-experimental

npm i https://pkg.pr.new/@tanstack/angular-query-experimental@10354

@tanstack/eslint-plugin-query

npm i https://pkg.pr.new/@tanstack/eslint-plugin-query@10354

@tanstack/preact-query

npm i https://pkg.pr.new/@tanstack/preact-query@10354

@tanstack/preact-query-devtools

npm i https://pkg.pr.new/@tanstack/preact-query-devtools@10354

@tanstack/preact-query-persist-client

npm i https://pkg.pr.new/@tanstack/preact-query-persist-client@10354

@tanstack/query-async-storage-persister

npm i https://pkg.pr.new/@tanstack/query-async-storage-persister@10354

@tanstack/query-broadcast-client-experimental

npm i https://pkg.pr.new/@tanstack/query-broadcast-client-experimental@10354

@tanstack/query-core

npm i https://pkg.pr.new/@tanstack/query-core@10354

@tanstack/query-devtools

npm i https://pkg.pr.new/@tanstack/query-devtools@10354

@tanstack/query-persist-client-core

npm i https://pkg.pr.new/@tanstack/query-persist-client-core@10354

@tanstack/query-sync-storage-persister

npm i https://pkg.pr.new/@tanstack/query-sync-storage-persister@10354

@tanstack/react-query

npm i https://pkg.pr.new/@tanstack/react-query@10354

@tanstack/react-query-devtools

npm i https://pkg.pr.new/@tanstack/react-query-devtools@10354

@tanstack/react-query-next-experimental

npm i https://pkg.pr.new/@tanstack/react-query-next-experimental@10354

@tanstack/react-query-persist-client

npm i https://pkg.pr.new/@tanstack/react-query-persist-client@10354

@tanstack/solid-query

npm i https://pkg.pr.new/@tanstack/solid-query@10354

@tanstack/solid-query-devtools

npm i https://pkg.pr.new/@tanstack/solid-query-devtools@10354

@tanstack/solid-query-persist-client

npm i https://pkg.pr.new/@tanstack/solid-query-persist-client@10354

@tanstack/svelte-query

npm i https://pkg.pr.new/@tanstack/svelte-query@10354

@tanstack/svelte-query-devtools

npm i https://pkg.pr.new/@tanstack/svelte-query-devtools@10354

@tanstack/svelte-query-persist-client

npm i https://pkg.pr.new/@tanstack/svelte-query-persist-client@10354

@tanstack/vue-query

npm i https://pkg.pr.new/@tanstack/vue-query@10354

@tanstack/vue-query-devtools

npm i https://pkg.pr.new/@tanstack/vue-query-devtools@10354

commit: b2e57fc

TkDodo · 2026-03-30T13:04:00Z

docs/framework/react/guides/important-defaults.md

  - set `staleTime` to `Infinity` to never trigger a refetch until the Query is [invalidated manually](./query-invalidation.md).
  - set `staleTime` to `'static'` to **never** trigger a refetch, even if the Query is [invalidated manually](./query-invalidation.md).

+> `'static'` and `Infinity` look similar but behave differently when `refetchOnMount`, `refetchOnWindowFocus`, or `refetchOnReconnect` are set to `"always"`. With `staleTime: Infinity`, those `"always"` triggers still fire. With `staleTime: 'static'`, they don't. The query stays frozen until you explicitly call `queryClient.resetQueries()`. Use `'static'` for data that cannot change while the app is running: feature flags fetched at boot, user permissions loaded at login, static reference tables. Use `Infinity` when you still want manual invalidation to work.


this sentence is great:

Use 'static' for data that cannot change while the app is running: feature flags fetched at boot, user permissions loaded at login, static reference tables. Use Infinity when you still want manual invalidation to work.

but the rest is a bit off. The ’always’ mention is also correct, but the biggest difference is that calling queryClient.invalidateQueries will still invalidate Infinity, but not ’static’.

So Infinity can be invalidated, static cannot.

The query stays frozen until you explicitly call queryClient.resetQueries()

Also not quite correct. The query will never refetch data once data is in the cache. So if data leaves the cache for whatever reason, it will of course need to fetch again. Reasons could be garbage collection (gcTime), calling removeQueries, queryClient.clear() or resetQueries, but it’s really not necessary to list them all, as the guides should teach concepts.

… 'static' vs Infinity

Zelys-DFKH

Good catch. Rewrote the blockquote to lead with invalidateQueries() behavior and dropped the resetQueries() reference.

docs(react): clarify staleTime 'static' vs Infinity with 'always' tri…

f4476da

…ggers

github-actions bot added the documentation Improvements or additions to documentation label Mar 29, 2026

TkDodo reviewed Mar 30, 2026

View reviewed changes

docs(react): lead with invalidateQueries() distinction for staleTime:…

b2e57fc

… 'static' vs Infinity

Zelys-DFKH commented Mar 30, 2026

View reviewed changes

TkDodo merged commit 3fd3460 into TanStack:main Mar 31, 2026
8 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(react): clarify staleTime 'static' vs Infinity with 'always' triggers#10354

docs(react): clarify staleTime 'static' vs Infinity with 'always' triggers#10354
TkDodo merged 2 commits intoTanStack:mainfrom
Zelys-DFKH:docs/stale-time-static

Zelys-DFKH commented Mar 29, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

nx-cloud bot commented Mar 29, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Mar 29, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

pkg-pr-new bot commented Mar 29, 2026 •

edited

Loading

Uh oh!

TkDodo Mar 30, 2026

Uh oh!

Zelys-DFKH left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

Zelys-DFKH commented Mar 29, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Checklist

Summary by CodeRabbit

Uh oh!

nx-cloud bot commented Mar 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Mar 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

pkg-pr-new bot commented Mar 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

TkDodo Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

Zelys-DFKH left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Zelys-DFKH commented Mar 29, 2026 •

edited by coderabbitai bot

Loading

nx-cloud bot commented Mar 29, 2026 •

edited

Loading

coderabbitai bot commented Mar 29, 2026 •

edited

Loading

pkg-pr-new bot commented Mar 29, 2026 •

edited

Loading