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
- Added clarification on behavioral differences between staleTime: Infinity and staleTime: 'static' when auto-refetch options are set to "always". Documents that refetch triggers still occur with staleTime: Infinity but not with staleTime: 'static', which may result in frozen queries.

…ggers

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

View your CI Pipeline Execution ↗ for commit f4476da

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

☁️ Nx Cloud last updated this comment at 2026-03-29 21:04:13 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: dfe8736c-1051-41bb-8b55-52253e5acd1b

📥 Commits

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

📒 Files selected for processing (1)

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

📝 Walkthrough

Walkthrough

A documentation update was added to the important-defaults guide clarifying the behavioral distinction between staleTime: Infinity and staleTime: 'static' when refetch options are set to "always", explaining how queries become frozen with the latter option until explicitly reset.

Changes

Cohort / File(s)	Summary
Documentation Update `docs/framework/react/guides/important-defaults.md`	Added advisory note explaining the behavioral difference between `staleTime: Infinity` and `staleTime: 'static'` when refetch-on-mount, refetch-on-window-focus, or refetch-on-reconnect are set to `"always"`, clarifying that "always" triggers still occur with Infinity but not with 'static', and providing guidance on which option to use.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Poem

🐰 A note we add with gentle care,
To clarify what's frozen there,
When 'static' freezes time in place,
And Infinity keeps up the race,
Our docs now shine so crystal clear! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main documentation change: clarifying the behavioral distinction between staleTime 'static' and Infinity with 'always' refetch triggers.
Description check	✅ Passed	The description includes a clear summary of changes and completed the checklist, but it diverges from the repository's template structure with custom formatting instead of using the specified template sections.
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: f4476da

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

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
Zelys-DFKH wants to merge 1 commit 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

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

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

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

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