Fix element scroll restoration reset

[LevDomasnih]

Summary

Fixes #7687.

When a non-window scroll target is restored from the scroll restoration cache, the later scroll-to-top fallback can still reset that same element if it is also listed in scrollToTopSelectors. This keeps track of restored elements during onRendered and skips those elements when applying the fallback reset.

Validation

• npm_config_cache=/tmp/codex-npm-cache npx -y pnpm@11.9.0 --filter @tanstack/history build
• npm_config_cache=/tmp/codex-npm-cache npx -y pnpm@11.9.0 --filter @tanstack/router-core exec vitest run tests/scroll-restoration.test.ts

Summary by CodeRabbit

• Bug Fixes
  • Fixed element scroll restoration so previously restored scroll positions are no longer overwritten by “scroll to top” behavior on the same render cycle.
  • Improved scroll handling for pages using both scroll restoration and scroll-to-top selectors, reducing unexpected jumps.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7d612d9c-6e02-4a7d-8397-4143c030dce3

📥 Commits

Reviewing files that changed from the base of the PR and between bb2daa6 and 784dfc4.

📒 Files selected for processing (3)

• .changeset/scroll-restoration-elements.md
• packages/router-core/src/scroll-restoration.ts
• packages/router-core/tests/scroll-restoration.test.ts

---

📝 Walkthrough

Walkthrough

Fixes a bug where DOM elements restored from scroll cache were subsequently reset to (0, 0) by the scrollToTopSelectors fallback. A restoredElements Set is introduced to record restored non-window elements, and the scrollToTopSelectors loop now skips any element present in that set.

Element scroll restoration fix

Layer / File(s)	Summary
restoredElements tracking and guard packages/router-core/src/scroll-restoration.ts	Adds a restoredElements Set<Element> | undefined variable, populates it when restoring element scroll positions from cache, and guards the scrollToTopSelectors loop to skip elements already in the set.
Test helper and new test case packages/router-core/tests/scroll-restoration.test.ts	Extends the createRouter test helper with a scrollToTopSelectors option, adds document.body.innerHTML = '' to afterEach cleanup, and adds a test verifying that restored elements are not reset by scrollToTopSelectors during onRendered.
Changeset .changeset/scroll-restoration-elements.md	Adds a patch changeset entry for @tanstack/router-core documenting the fix.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• TanStack/router#7447: Directly modifies the same setupScrollRestoration code path involving element scroll positions and scrollToTopSelectors interaction.

Suggested labels

package: router-core

🐇 A scroll was saved, a position held dear,
But scrollToTopSelectors kept wiping it clear!
Now a Set guards the restored with care,
No fallback shall clobber what's already there. 🌿
Hop hop, the scroll stays right where it should be!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ 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%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: preventing element scroll restoration from being reset.
Linked Issues check	✅ Passed	The code tracks restored elements and skips them in the scroll-to-top fallback, matching #7687's required behavior.
Out of Scope Changes check	✅ Passed	The changes are limited to the bug fix, its tests, and the accompanying changeset.

✨ 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

• X
• Mastodon
• Reddit
• LinkedIn

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