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.
- Provides guidance and a full example for disabling built-in retries and implementing a custom background retry strategy, plus recommendations for controlling retry timing and ensuring desired behavior while a page is inactive.

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

⚠️ No Changeset found

Latest commit: ed87922

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 subsection describing how refetchInterval interacts with refetchIntervalInBackground: true, noting built-in retries pause when the tab is inactive and showing a full example that disables retry 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 a "Background Retry Behavior" section explaining that `refetchInterval` with `refetchIntervalInBackground: true` still pauses built-in retries when the tab is inactive, and included a complete example showing `refetchInterval`, `refetchIntervalInBackground: true`, and `retry: false` plus a custom refetch function for continuous background retries.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Review focus: verify example code correctness, clarity of wording around pause behavior, and that configuration flags are described accurately.

Poem

🐰 I hop through docs at evening’s light,
Retries that pause when tabs take flight.
Built-ins rest while backgrounds roam,
Custom beats keep fetches 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 aligns with the main change described in the raw summary. The title clearly identifies that documentation was added about background retry pausing behavior for React Query v5. It uses specific, descriptive language that avoids vague terms and would allow teammates scanning the history to immediately understand the primary change. The title appropriately summarizes the addition of the "Background Retry Behavior" subsection to the query-retries guide.
Description Check	✅ Passed	The PR description follows the required template structure with all three main sections present. The "Changes" section explains what was added and references the related PR #9563, the "Checklist" section has both items appropriately marked as complete, and the "Release Impact" section correctly identifies this as docs/CI/dev-only with the no-release checkbox marked. All required information is present and properly addressed according to the template.

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

📒 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 added 2 commits October 27, 2025 10:59

docs: add react background retry pausing documentation for v5

f8243e3

docs: add background retry behavior to query-retries guide

ed87922

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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!

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