Enhance scroll restoration documentation for TanStack Query

[dilmuhammad006]

Explain how TanStack Query improves scroll restoration in SPAs by caching data and preventing UI resets.

🎯 Changes

✅ 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
  • Clarified scroll restoration behavior: the library itself doesn't perform restoration but caches query results to prevent refetch-induced UI resets, enabling instant rendering and stable layout when navigating back.
  • Added guidance on relying on router-level or custom scroll restoration and on cache lifetime/placeholder data affecting whether restoration works automatically.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: e039391

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]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

Clarifies in the React scroll restoration guide that TanStack Query does not perform scroll restoration itself; it preserves query results in cache (and supports placeholderData/keepPreviousData) so routers or custom solutions can reliably restore scroll when data remains cached.

Changes

Cohort / File(s)	Summary
Documentation: Scroll Restoration Guide docs/framework/react/guides/scroll-restoration.md	Added two explanatory paragraphs clarifying that TanStack Query does not implement scroll restoration but prevents refetch-induced UI resets by caching previous query results (and can use placeholderData / keepPreviousData), enabling router-driven scroll restoration to work reliably while cached data persists.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• Enhance scroll restoration documentation for TanStack Query #9987 — Edits the same documentation file and adds similar clarifying paragraphs about TanStack Query's role in scroll restoration.

Poem

🐇 I hop through pages, tidy and spry,

Caching the crumbs where scrolls lie,
When routers remember each place,
Back you return with steady grace,
A gentle scroll — no layout sigh.

Pre-merge checks and finishing touches

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The PR description partially follows the template with a summary statement, but the '🎯 Changes' section lacks detail about what was actually modified, and both checklist items and release impact options remain unchecked.	Complete the '🎯 Changes' section with specific details about the modifications, and clarify the release impact by checking the appropriate checkbox (docs/CI/dev-only in this case).

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Enhance scroll restoration documentation for TanStack Query' clearly and concisely describes the main change—adding documentation enhancements to the scroll restoration guide.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 4d4455b and e039391.

📒 Files selected for processing (1)

• docs/framework/react/guides/scroll-restoration.md

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

docs/framework/react/guides/scroll-restoration.md (2)

8-8: Verify API names and consider adding usage examples.

The explanation is technically sound and clarifies an important distinction between TanStack Query's role (caching) and the router's role (restoration). However, I'd recommend verifying that placeholderData and keepPreviousData are the exact API names in the current version of TanStack Query, and consider adding a brief code example showing how to enable this behavior.

For instance, a simple example like:

// Enable scroll restoration by preventing UI resets during navigation
const { data } = useQuery({
  queryKey: ['page', pageNum],
  queryFn: fetchPageData,
  placeholderData: keepPreviousData, // Keeps previous data visible while fetching
})

This would make the guidance more actionable for developers implementing scroll restoration.

---

10-10: Verify default cache times and refine phrasing for clarity.

The technical content is accurate, but the documentation could be clearer:

1. Verify defaults: Confirm whether the 5-minute default refers to staleTime, garbage collection interval (gcTime in v5+), or both. This is crucial for readers to understand when scroll restoration might break.

2. Refine phrasing: Replace the casual "Just Works™️" with more precise language, and clarify the conditional nature of this behavior:

   Out of the box, scroll restoration for all queries (including paginated 
   and infinite queries) works automatically in TanStack Query, provided 
   your queries are cached long enough (default: 5 minutes) and haven't 
   been garbage collected.
   

This makes it explicit that scroll restoration depends on cache configuration, not just on using TanStack Query.

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ee16773 and 4d4455b.

📒 Files selected for processing (1)

• docs/framework/react/guides/scroll-restoration.md