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" describing how refresh intervals behave when a tab is inactive and how built-in retries interact with background execution.
- Includes a complete configuration example showing refetchInterval, refetchIntervalInBackground, and disabling built-in retries in favor of a custom refetch strategy, plus guidance on controlling retry behavior during background execution.

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

⚠️ No Changeset found

Latest commit: 305be88

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" documentation section explaining how refetchInterval interacts with refetchIntervalInBackground: true, that built-in retries pause when the tab is inactive, and showing an example disabling built-in retries (retry: false) in favor of a custom background refetch strategy.

Changes

Cohort / File(s)	Summary
Documentation: Background Retry Behavior `docs/framework/react/guides/query-retries.md`	Added "Background Retry Behavior" section describing interaction between `refetchInterval` and `refetchIntervalInBackground`, clarified that built-in retries pause when the tab is inactive, and included a full example using `refetchInterval`, `refetchIntervalInBackground: true`, and `retry: false` with a custom refetch strategy for continuous background retries.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I nibble docs by moonlight’s glow,
Explaining retries that ebb and flow.
Tabs nap, built-ins pause their chase,
Custom hops keep fetches in place. 🥕✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title "docs(react-query): add react background retry pausing documentation for v5" is clear, specific, and directly summarizes the main change in the pull request. It accurately reflects the addition of documentation explaining how query retries are paused in background tabs and the interaction with refetchIntervalInBackground. The title uses standard documentation formatting with the package scope, is concise as a single sentence, and provides sufficient context for a developer scanning history to understand the primary change without being overly verbose.
Description Check	✅ Passed	The pull request description follows the required template structure with all three sections present: "🎯 Changes", "✅ Checklist", and "🚀 Release Impact". The Changes section includes a reference to the related PR (#9563), clearly describes the documentation addition about background retry pausing, and notes the context of overriding refetchIntervalInBackground. Both checklist items are properly marked as completed, and the Release Impact is correctly checked as docs/CI/dev-only with no changeset needed, which is appropriate for documentation-only changes.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ 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 01fa7bc and 305be88.

📒 Files selected for processing (1)

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

🔇 Additional comments (1)

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

82-105: ✅ Excellent documentation addition with correct v5 API.

The new "Background Retry Behavior" section accurately explains the interaction between retries and background tabs, and the code example correctly demonstrates the v5 refetchInterval API signature (passing query instead of the v4 (data, query) signature). The recommended pattern—disabling built-in retries (retry: false) and implementing custom retry logic via refetchInterval—is a sound approach that gives developers control while maintaining background activity.

The progression from problem statement to solution to explanation is clear and helpful for users encountering this behavior. The fix from the previous review is confirmed to be in place.

_{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 from dca7bac to 01fa7bc Compare October 18, 2025 09:12

Hellol77 added 2 commits October 18, 2025 18:18

docs: add react background retry pausing documentation for v5

b3b65e9

docs: add background retry behavior to query-retries guide

305be88

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

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

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

Are you sure you want to change the base?

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!

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