docs(react-query): add react background retry pausing documentation for v5 #9755

Hellol77 · 2025-10-14T15:36:20Z

🎯 Changes

Related to #9563
Added react-query documentation on how query retries are paused in background tabs, explaining why this overrides refetchIntervalInBackground

Would love to hear your thoughts on this direction.

✅ Checklist

I have followed the steps in the Contributing guide.
I have tested this code locally with pnpm run test:pr.

🚀 Release Impact

This change affects published code, and I have generated a changeset.
This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

Documentation
- Added a new guide "Background Retry Behavior" explaining how refresh intervals behave when a tab is inactive and how built-in retries interact with background execution.
- Includes guidance and a full example for disabling built-in retries and implementing a custom background retry strategy, with recommendations for controlling retry timing while a page is inactive.

changeset-bot · 2025-10-14T15:36:24Z

⚠️ No Changeset found

Latest commit: 117be09

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

coderabbitai · 2025-10-14T15:36:45Z

Walkthrough

Added a "Background Retry Behavior" docs subsection clarifying that built-in retry/refetch pauses when a tab is inactive even with refetchIntervalInBackground: true, and showing a complete example that disables built-in retries and implements a custom background refetch strategy.

Changes

Cohort / File(s)	Summary
Documentation: Background Retry Behavior `docs/framework/react/guides/query-retries.md`	Added a "Background Retry Behavior" section describing how `refetchInterval` interacts with `refetchIntervalInBackground: true` (built-in retries still pause when the tab is inactive). Included a full example that sets `refetchInterval`, `refetchIntervalInBackground: true`, and `retry: false`, and demonstrates a custom `refetchInterval` function for continuous background retries.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Pay attention to the example code correctness and clarity around pause behavior and configuration flags.

Poem

🐰 I nibble docs in moonlit light,
Retries that pause when tabs take flight.
Built-ins rest while backgrounds roam,
I craft a loop to keep them home.
🥕

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The PR title "docs(react-query): add react background retry pausing documentation for v5" directly and accurately reflects the main change in the pull request. The title clearly identifies that documentation is being added about background retry pausing behavior in React Query v5. The title is concise, specific, and provides sufficient context for a developer scanning the history to understand the primary change without ambiguity.
Description Check	✅ Passed	The PR description properly follows the required template structure with all three main sections present: "🎯 Changes", "✅ Checklist", and "🚀 Release Impact". The description includes meaningful context about the changes (explaining what was added regarding retry pausing in background tabs), relevant reference to PR #9563, and correctly marks the appropriate checklist items as completed. The release impact classification as "docs/CI/dev-only (no release)" is appropriate for documentation-only changes.

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ed87922 and 117be09.

📒 Files selected for processing (1)

docs/framework/react/guides/query-retries.md (1 hunks)

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

docs/framework/react/guides/query-retries.md

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

coderabbitai

Actionable comments posted: 2

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 36ece87 and e704a9b.

📒 Files selected for processing (1)

docs/framework/react/guides/background-retry-pausing.md (1 hunks)

🧰 Additional context used

🪛 LanguageTool

docs/framework/react/guides/background-retry-pausing.md

[grammar] ~12-~12: There might be a mistake here.
Context: ...ts, including: - Initial query failures - Refetch interval failures - Manual refet...

(QB_NEW_EN)

[grammar] ~13-~13: There might be a mistake here.
Context: ...ery failures - Refetch interval failures - Manual refetch failures [//]: # 'Exampl...

(QB_NEW_EN)

docs/framework/react/guides/background-retry-pausing.md

coderabbitai · 2025-10-14T15:39:19Z

docs/framework/react/guides/background-retry-pausing.md

+```tsx
+const { data } = useQuery({
+  queryKey: ['non-critical-data'],
+  queryFn: fetchData,
+  refetchInterval: 30000,
+  refetchIntervalInBackground: true,
+  retry: (failureCount, error) => {
+    // Only retry when tab is focused
+    return focusManager.isFocused() ? failureCount < 3 : false
+  },
+})


⚠️ Potential issue | 🟡 Minor

Import missing in snippet

This snippet calls focusManager.isFocused() but does not show an import. For copy-paste correctness, add import { focusManager } from '@tanstack/react-query' (or include it in the preceding code fence).

🤖 Prompt for AI Agents

In docs/framework/react/guides/background-retry-pausing.md around lines 115 to 125, the snippet uses focusManager.isFocused() but does not show its import; add an import line for focusManager from '@tanstack/react-query' at the top of the code example (or include it in the preceding code fence) so the snippet is copy-paste ready.

TkDodo

can you add this to the query retry guide please:

https://tanstack.com/query/v5/docs/framework/react/guides/query-retries

also maybe trim it down a bit because I don’t think it’s such an important / relevant situation that we need to dedicate a full guide to it.

at the end of the day, if you have refetchInterval and refetchIntervalInBackground turned on, you can just turn off retries and maybe implement a custom refetchInterval function that refetches more often when the query is in error state to kinda imitate what retries do...

coderabbitai

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e704a9b and 4ec77ca.

📒 Files selected for processing (1)

docs/framework/react/guides/query-retries.md (1 hunks)

🔇 Additional comments (2)

docs/framework/react/guides/query-retries.md (2)

82-84: Verify the retry-pausing behavior claim and its interaction with refetchIntervalInBackground.

The section asserts that "retries will pause when the browser tab is inactive" when using refetchIntervalInBackground: true. This is a critical claim for users to rely on. The explanation also states that "retries respect the same focus-based behavior as regular refetches," but this distinction between retries and refetches as separate mechanisms could be clearer upfront.

Please verify:

That retries indeed pause during tab inactivity when refetchIntervalInBackground: true is set

The distinction between built-in retry behavior and refetchInterval refetch behavior in the context of background tab inactivity

Whether this is the intended behavior or a side-effect that's being documented as a known limitation

Since this change relates to issue #9563, confirming the behavior against that issue would help validate this claim.

84-105: Documentation structure and clarity are solid.

The section logically flows from problem identification → explanation of root cause → proposed solution → practical code example. The use of consistent documentation markers ([//]: # 'Example4') aligns with the existing file style. The code example demonstrates a pragmatic workaround (disabling retries and using custom refetchInterval logic) that gives users more explicit control.

docs/framework/react/guides/query-retries.md

Hellol77 · 2025-10-18T09:24:21Z

@TkDodo Thanks for the feedback! I've updated the documentation as suggested.
Added a section to the query-retries guide instead of creating a separate guide. The section explains the background retry pausing behavior and provides the custom refetch strategy approach you mentioned.

github-actions bot added the documentation Improvements or additions to documentation label Oct 14, 2025

coderabbitai bot reviewed Oct 14, 2025

View reviewed changes

TkDodo reviewed Oct 16, 2025

View reviewed changes

coderabbitai bot reviewed Oct 18, 2025

View reviewed changes

docs/framework/react/guides/query-retries.md Show resolved Hide resolved

Hellol77 force-pushed the docs/background-retry-pausing-v5 branch 2 times, most recently from 01fa7bc to 305be88 Compare October 18, 2025 09:18

Hellol77 force-pushed the docs/background-retry-pausing-v5 branch from 37f5942 to ed87922 Compare October 27, 2025 01:59

Hellol77 added 2 commits October 31, 2025 16:20

docs: add react background retry pausing documentation for v5

951a5df

docs: add background retry behavior to query-retries guide

117be09

Hellol77 force-pushed the docs/background-retry-pausing-v5 branch from ed87922 to 117be09 Compare October 31, 2025 07:20

TkDodo merged commit 14a032d into TanStack:main Nov 1, 2025
2 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

docs(react-query): add react background retry pausing documentation for v5 #9755

docs(react-query): add react background retry pausing documentation for v5 #9755

Hellol77 commented Oct 14, 2025 •

edited by coderabbitai bot

Loading

Uh oh!

changeset-bot bot commented Oct 14, 2025 •

edited

Loading

Uh oh!

coderabbitai bot commented Oct 14, 2025 •

edited

Loading

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

coderabbitai bot Oct 14, 2025

Uh oh!

TkDodo left a comment

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Hellol77 commented Oct 18, 2025 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

docs(react-query): add react background retry pausing documentation for v5 #9755

docs(react-query): add react background retry pausing documentation for v5 #9755

Conversation

Hellol77 commented Oct 14, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎯 Changes

✅ Checklist

🚀 Release Impact

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

coderabbitai bot commented Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Pre-merge checks and finishing touches

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai bot Oct 14, 2025

Choose a reason for hiding this comment

Uh oh!

TkDodo left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Hellol77 commented Oct 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Hellol77 commented Oct 14, 2025 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Oct 14, 2025 •

edited

Loading

coderabbitai bot commented Oct 14, 2025 •

edited

Loading

Hellol77 commented Oct 18, 2025 •

edited

Loading