fix: scroll restoration upon browser forward navigation (#7055)

schiller-manuel · web-flow · commit 42c3f3b3a3a4 · 2026-03-27T01:24:06.000+01:00
diff --git a/.changeset/fifty-eagles-breathe.md b/.changeset/fifty-eagles-breathe.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/router-core': patch
+---
+
+Fix a regression where browser back/forward navigation could fail to restore the previous scroll position for an existing history entry.
diff --git a/e2e/react-router/scroll-restoration-sandbox-vite/tests/app.spec.ts b/e2e/react-router/scroll-restoration-sandbox-vite/tests/app.spec.ts
@@ -9,6 +9,67 @@ test('Smoke - Renders home', async ({ page }) => {
   ).toBeVisible()
 })
 
+test('restores the prior scroll position after browser back then forward', async ({
+  page,
+}) => {
+  await page.goto(toRuntimePath('/'))
+  await page.getByRole('link', { name: 'Head-/normal-page' }).click()
+  await page.waitForURL('**/normal-page')
+  await expect(page.getByTestId('at-the-top')).toBeInViewport()
+
+  const scrollY = await page.evaluate(async () => {
+    window.scrollTo(0, document.documentElement.scrollHeight)
+    await new Promise((resolve) => requestAnimationFrame(() => resolve(null)))
+    return window.scrollY
+  })
+
+  expect(scrollY).toBeGreaterThan(0)
+  await expect(page.getByTestId('at-the-bottom')).toBeInViewport()
+
+  await page.goBack()
+  await expect(
+    page.getByRole('heading', { name: 'Welcome Home!' }),
+  ).toBeVisible()
+
+  await page.goForward()
+  await page.waitForURL('**/normal-page')
+  await page.waitForFunction(
+    (expectedScrollY) => Math.abs(window.scrollY - expectedScrollY) <= 2,
+    scrollY,
+  )
+  await expect(page.getByTestId('at-the-bottom')).toBeInViewport()
+})
+
+test('restores the prior scroll position after browser back navigation', async ({
+  page,
+}) => {
+  await page.goto(toRuntimePath('/normal-page'))
+  await expect(page.getByTestId('at-the-top')).toBeInViewport()
+
+  const scrollY = await page.evaluate(async () => {
+    window.scrollTo(0, document.documentElement.scrollHeight)
+    await new Promise((resolve) => requestAnimationFrame(() => resolve(null)))
+    return window.scrollY
+  })
+
+  expect(scrollY).toBeGreaterThan(0)
+  await expect(page.getByTestId('at-the-bottom')).toBeInViewport()
+
+  await page.getByRole('link', { name: 'Foot-/', exact: true }).click()
+  await page.waitForURL('**/')
+  await expect(
+    page.getByRole('heading', { name: 'Welcome Home!' }),
+  ).toBeVisible()
+
+  await page.goBack()
+  await page.waitForURL('**/normal-page')
+  await page.waitForFunction(
+    (expectedScrollY) => Math.abs(window.scrollY - expectedScrollY) <= 2,
+    scrollY,
+  )
+  await expect(page.getByTestId('at-the-bottom')).toBeInViewport()
+})
+
 const pages = [
   linkOptions({ to: '/normal-page' }),
   linkOptions({ to: '/lazy-page' }),
diff --git a/packages/router-core/src/scroll-restoration.ts b/packages/router-core/src/scroll-restoration.ts
@@ -258,24 +258,6 @@ export function setupScrollRestoration(router: AnyRouter, force?: boolean) {
       return
     }
 
-    const fromIndex = event.fromLocation?.state.__TSR_index
-    const toIndex = event.toLocation.state.__TSR_index
-    // Clear on forward navigations, and on same-entry replace navigations where
-    // the href changed. Preserve back/restore entries so they can be restored.
-    const shouldClearCache =
-      typeof fromIndex === 'number' && typeof toIndex === 'number'
-        ? toIndex > fromIndex ||
-          (toIndex === fromIndex &&
-            event.fromLocation?.href !== event.toLocation.href)
-        : true
-
-    if (shouldClearCache) {
-      cache.set((state) => {
-        delete state[cacheKey]
-        return state
-      })
-    }
-
     ignoreScroll = true
 
     try {

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@tanstack/router-core': patch
 +---
++
 +Fix a regression where browser back/forward navigation could fail to restore the previous scroll position for an existing history entry.