fix: scroll restoration upon browser forward navigation

[schiller-manuel]

Summary by CodeRabbit

• Bug Fixes

  • Restored reliable scroll-position recovery during browser back/forward navigation so revisiting pages correctly restores the previous scroll location.

• Tests

  • Added end-to-end tests that verify scroll restoration across history navigation (back/forward and link navigation scenarios).

[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: ed40289e-f51c-439b-b193-00150b34823a

📥 Commits

Reviewing files that changed from the base of the PR and between 4b13939 and 59477ae.

📒 Files selected for processing (3)

• .changeset/fifty-eagles-breathe.md
• e2e/react-router/scroll-restoration-sandbox-vite/tests/app.spec.ts
• packages/router-core/src/scroll-restoration.ts

💤 Files with no reviewable changes (1)

• packages/router-core/src/scroll-restoration.ts

✅ Files skipped from review due to trivial changes (1)

• .changeset/fifty-eagles-breathe.md

---

📝 Walkthrough

Walkthrough

Removes conditional cache-clearing logic that caused scroll positions to be lost during browser back/forward navigation; always proceeds with the existing scroll restoration flow. Adds Playwright e2e tests and a Changeset declaring a patch release for @tanstack/router-core. (48 words)

Changes

Cohort / File(s)	Summary
Release Documentation \.changeset/fifty-eagles-breathe.md	Added a changeset declaring a patch release for @tanstack/router-core documenting the scroll restoration fix.
Scroll Restoration Fix packages/router-core/src/scroll-restoration.ts	Removed conditional logic that deleted cached scroll entries based on navigation indices/href; restoration path now proceeds without that pre-restore cache invalidation.
E2E Tests e2e/react-router/scroll-restoration-sandbox-vite/tests/app.spec.ts	Added two Playwright tests validating scroll position and sentinel visibility are restored after back/forward navigation (asserting scrollY within 2px).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I hopped through history, found the lost spot,
A cache no longer hiding what I sought.
Back and forth, the page remembers me,
Soft-scroll home, as snug as can be. ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main fix: addressing scroll restoration regression during browser forward navigation. It directly relates to the core changes across all modified files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix-forward-scroll-restoration

---

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 59477ae

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	✅ Succeeded	12m 37s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	10s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-03-27 00:16:33 UTC

[github-actions]

🚀 Changeset Version Preview

1 package(s) bumped directly, 21 bumped as dependents.

🟩 Patch bumps

Package	Version	Reason
@tanstack/router-core	1.168.5 → 1.168.6	Changeset
@tanstack/react-router	1.168.6 → 1.168.7	Dependent
@tanstack/react-start	1.167.11 → 1.167.12	Dependent
@tanstack/react-start-client	1.166.21 → 1.166.22	Dependent
@tanstack/react-start-server	1.166.21 → 1.166.22	Dependent
@tanstack/router-cli	1.166.21 → 1.166.22	Dependent
@tanstack/router-generator	1.166.20 → 1.166.21	Dependent
@tanstack/router-plugin	1.167.7 → 1.167.8	Dependent
@tanstack/router-vite-plugin	1.166.22 → 1.166.23	Dependent
@tanstack/solid-router	1.168.5 → 1.168.6	Dependent
@tanstack/solid-start	1.167.10 → 1.167.11	Dependent
@tanstack/solid-start-client	1.166.19 → 1.166.20	Dependent
@tanstack/solid-start-server	1.166.19 → 1.166.20	Dependent
@tanstack/start-client-core	1.167.5 → 1.167.6	Dependent
@tanstack/start-plugin-core	1.167.12 → 1.167.13	Dependent
@tanstack/start-server-core	1.167.5 → 1.167.6	Dependent
@tanstack/start-static-server-functions	1.166.21 → 1.166.22	Dependent
@tanstack/start-storage-context	1.166.19 → 1.166.20	Dependent
@tanstack/vue-router	1.168.5 → 1.168.6	Dependent
@tanstack/vue-start	1.167.10 → 1.167.11	Dependent
@tanstack/vue-start-client	1.166.19 → 1.166.20	Dependent
@tanstack/vue-start-server	1.166.19 → 1.166.20	Dependent

[github-actions]

Bundle Size Benchmarks

• Commit: 5c5a4359e837
• Measured at: 2026-03-27T00:07:23.520Z
• Baseline source: history:5ca661c2f8a7
• Dashboard: bundle-size history

Scenario	Current (gzip)	Delta vs baseline	Raw	Brotli	Trend
react-router.minimal	87.47 KiB	-65 B (-0.07%)	275.67 KiB	75.99 KiB	███▇▇▃▃▂▂▂▂▁
react-router.full	90.76 KiB	-78 B (-0.08%)	286.86 KiB	78.96 KiB	███▇▇▃▃▂▂▂▂▁
solid-router.minimal	35.51 KiB	-56 B (-0.15%)	107.04 KiB	31.90 KiB	███▅▅▅▅▂▂▂▂▁
solid-router.full	39.98 KiB	-60 B (-0.15%)	120.57 KiB	35.84 KiB	███▄▄▄▄▃▃▃▃▁
vue-router.minimal	53.36 KiB	-61 B (-0.11%)	152.97 KiB	47.91 KiB	█████▂▂▂▂▂▂▁
vue-router.full	58.22 KiB	-61 B (-0.10%)	168.43 KiB	52.08 KiB	█████▃▃▂▂▂▂▁
react-start.minimal	101.99 KiB	-67 B (-0.06%)	323.85 KiB	88.24 KiB	███▆▆▂▂▂▂▂▂▁
react-start.full	105.36 KiB	-70 B (-0.06%)	334.20 KiB	91.10 KiB	███▇▇▂▂▂▂▂▂▁
solid-start.minimal	49.60 KiB	-51 B (-0.10%)	153.22 KiB	43.67 KiB	███▅▅▅▅▂▂▂▂▁
solid-start.full	55.10 KiB	-70 B (-0.12%)	169.46 KiB	48.43 KiB	███▄▄▄▄▃▃▃▃▁

Trend sparkline is historical gzip bytes ending with this PR measurement; lower is better.

[pkg-pr-new]

More templates

• tanstack-router-solid-example-authenticated-routes
• tanstack-router-solid-example-authenticated-routes-firebase
• tanstack-router-solid-example-basic
• tanstack-router-solid-example-basic-default-search-params
• tanstack-router-solid-example-basic-devtools-panel
• tanstack-router-solid-example-basic-file-based
• tanstack-router-solid-example-basic-non-nested-devtools
• tanstack-router-solid-example-basic-solid-query
• tanstack-router-solid-example-basic-solid-query-file-based
• tanstack-router-solid-example-basic-ssr-file-based
• tanstack-router-solid-example-basic-ssr-streaming-file-based
• tanstack-router-solid-example-basic-virtual-file-based
• tanstack-router-solid-example-basic-virtual-inside-file-based
• tanstack-router-solid-example-deferred-data
• tanstack-router-solid-i18n-paraglide
• tanstack-router-solid-example-kitchen-sink
• tanstack-router-solid-example-kitchen-sink-file-based
• tanstack-router-solid-example-kitchen-sink-solid-query
• tanstack-router-solid-example-kitchen-sink-solid-query-file-based
• tanstack-router-solid-example-large-file-based
• tanstack-router-solid-example-location-masking
• tanstack-router-solid-example-navigation-blocking
• tanstack-router-solid-example-quickstart
• tanstack-router-solid-example-quickstart-esbuild-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-router-solid-example-quickstart-rspack-file-based
• tanstack-router-solid-example-quickstart-webpack-file-based
• @tanstack/router-solid-mono-simple
• router-solid-mono-simple-lazy
• router-solid-monorepo-solid-query
• tanstack-router-solid-example-scroll-restoration
• tanstack-solid-router-search-validator-adapters
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-auth
• tanstack-solid-start-example-basic-authjs
• tanstack-solid-start-example-basic-cloudflare
• tanstack-solid-start-example-basic-netlify
• tanstack-solid-start-example-basic-nitro
• tanstack-start-example-basic-solid-query
• tanstack-solid-start-example-basic-static
• tanstack-solid-start-bun-hosting
• tanstack-solid-start-example-convex-better-auth
• tanstack-solid-start-example-counter
• tanstack-solid-start-i18n-paraglide
• tanstack-solid-start-example-large
• tanstack-solid-start-streaming-data-from-server-functions
• tanstack-solid-start-example-supabase-basic
• tanstack-solid-start-tailwind-v4
• tanstack-router-solid-example-view-transitions
• tanstack-router-solid-example-with-framer-motion
• tanstack-router-solid-example-with-trpc
• tanstack-router-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc
• tanstack-router-react-example-authenticated-routes
• tanstack-router-react-example-authenticated-routes-firebase
• tanstack-router-react-example-basic
• tanstack-router-react-example-basic-default-search-params
• tanstack-router-react-example-basic-devtools-panel
• tanstack-router-react-example-basic-file-based
• tanstack-router-react-example-basic-non-nested-devtools
• tanstack-router-react-example-react-query
• tanstack-router-react-example-basic-react-query-file-based
• tanstack-router-react-example-basic-ssr-file-based
• tanstack-router-react-example-basic-ssr-streaming-file-based
• tanstack-router-react-example-basic-virtual-file-based
• tanstack-router-react-example-basic-virtual-inside-file-based
• tanstack-router-react-example-deferred-data
• tanstack-router-i18n-paraglide
• tanstack-router-react-example-kitchen-sink
• tanstack-router-react-example-kitchen-sink-file-based
• tanstack-router-react-example-kitchen-sink-react-query
• tanstack-router-react-example-kitchen-sink-react-query-file-based
• tanstack-router-react-example-large-file-based
• tanstack-router-react-example-location-masking
• tanstack-router-react-example-navigation-blocking
• tanstack-router-react-example-quickstart
• tanstack-router-react-example-quickstart-esbuild-file-based
• tanstack-router-react-example-quickstart-file-based
• tanstack-router-react-example-quickstart-rspack-file-based
• tanstack-router-react-example-quickstart-webpack-file-based
• router-monorepo-react-query
• router-mono-simple
• router-mono-simple-lazy
• tanstack-router-react-example-scroll-restoration
• tanstack-search-validator-adapters
• tanstack-start-example-bare
• tanstack-start-example-basic
• tanstack-start-example-basic-auth
• tanstack-router-react-example-basic-authjs
• tanstack-start-example-basic-cloudflare
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-rsc
• tanstack-start-example-basic-static
• tanstack-start-bun-hosting
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-i18n-paraglide
• tanstack-start-example-large
• tanstack-start-example-material-ui
• tanstack-start-streaming-data-from-server-functions
• tanstack-start-example-supabase-basic
• tanstack-start-tailwind-v4
• tanstack-start-example-trellaux
• tanstack-start-example-workos
• tanstack-router-react-example-view-transitions
• tanstack-router-react-example-with-framer-motion
• tanstack-router-react-example-with-trpc
• tanstack-router-react-example-with-trpc-react-query

@tanstack/arktype-adapter

npm i https://pkg.pr.new/@tanstack/arktype-adapter@7055

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/@tanstack/eslint-plugin-router@7055

@tanstack/history

npm i https://pkg.pr.new/@tanstack/history@7055

@tanstack/nitro-v2-vite-plugin

npm i https://pkg.pr.new/@tanstack/nitro-v2-vite-plugin@7055

@tanstack/react-router

npm i https://pkg.pr.new/@tanstack/react-router@7055

@tanstack/react-router-devtools

npm i https://pkg.pr.new/@tanstack/react-router-devtools@7055

@tanstack/react-router-ssr-query

npm i https://pkg.pr.new/@tanstack/react-router-ssr-query@7055

@tanstack/react-start

npm i https://pkg.pr.new/@tanstack/react-start@7055

@tanstack/react-start-client

npm i https://pkg.pr.new/@tanstack/react-start-client@7055

@tanstack/react-start-server

npm i https://pkg.pr.new/@tanstack/react-start-server@7055

@tanstack/router-cli

npm i https://pkg.pr.new/@tanstack/router-cli@7055

@tanstack/router-core

npm i https://pkg.pr.new/@tanstack/router-core@7055

@tanstack/router-devtools

npm i https://pkg.pr.new/@tanstack/router-devtools@7055

@tanstack/router-devtools-core

npm i https://pkg.pr.new/@tanstack/router-devtools-core@7055

@tanstack/router-generator

npm i https://pkg.pr.new/@tanstack/router-generator@7055

@tanstack/router-plugin

npm i https://pkg.pr.new/@tanstack/router-plugin@7055

@tanstack/router-ssr-query-core

npm i https://pkg.pr.new/@tanstack/router-ssr-query-core@7055

@tanstack/router-utils

npm i https://pkg.pr.new/@tanstack/router-utils@7055

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/@tanstack/router-vite-plugin@7055

@tanstack/solid-router

npm i https://pkg.pr.new/@tanstack/solid-router@7055

@tanstack/solid-router-devtools

npm i https://pkg.pr.new/@tanstack/solid-router-devtools@7055

@tanstack/solid-router-ssr-query

npm i https://pkg.pr.new/@tanstack/solid-router-ssr-query@7055

@tanstack/solid-start

npm i https://pkg.pr.new/@tanstack/solid-start@7055

@tanstack/solid-start-client

npm i https://pkg.pr.new/@tanstack/solid-start-client@7055

@tanstack/solid-start-server

npm i https://pkg.pr.new/@tanstack/solid-start-server@7055

@tanstack/start-client-core

npm i https://pkg.pr.new/@tanstack/start-client-core@7055

@tanstack/start-fn-stubs

npm i https://pkg.pr.new/@tanstack/start-fn-stubs@7055

@tanstack/start-plugin-core

npm i https://pkg.pr.new/@tanstack/start-plugin-core@7055

@tanstack/start-server-core

npm i https://pkg.pr.new/@tanstack/start-server-core@7055

@tanstack/start-static-server-functions

npm i https://pkg.pr.new/@tanstack/start-static-server-functions@7055

@tanstack/start-storage-context

npm i https://pkg.pr.new/@tanstack/start-storage-context@7055

@tanstack/valibot-adapter

npm i https://pkg.pr.new/@tanstack/valibot-adapter@7055

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/@tanstack/virtual-file-routes@7055

@tanstack/vue-router

npm i https://pkg.pr.new/@tanstack/vue-router@7055

@tanstack/vue-router-devtools

npm i https://pkg.pr.new/@tanstack/vue-router-devtools@7055

@tanstack/vue-router-ssr-query

npm i https://pkg.pr.new/@tanstack/vue-router-ssr-query@7055

@tanstack/vue-start

npm i https://pkg.pr.new/@tanstack/vue-start@7055

@tanstack/vue-start-client

npm i https://pkg.pr.new/@tanstack/vue-start-client@7055

@tanstack/vue-start-server

npm i https://pkg.pr.new/@tanstack/vue-start-server@7055

@tanstack/zod-adapter

npm i https://pkg.pr.new/@tanstack/zod-adapter@7055

commit: 59477ae

[codspeed-hq]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing fix-forward-scroll-restoration (59477ae) with main (5ca661c)¹}

Footnotes

1. No successful run was found on main (5c5a435) during the generation of this report, so 5ca661c was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩