fix(router-core): handle window and element scroll restoration independently

.changeset/fix-independent-scroll-targets.md

@@ -0,0 +1,13 @@
+---
+'@tanstack/router-core': patch
+---
+
+fix(router-core): handle window and element scroll restoration independently
+
+Window and element scroll targets are now handled independently. Restoring one target no longer suppresses resets for other uncached configured targets, and a restored element is no longer reset when the window has no cached position.
+
+Hash navigation no longer resets elements configured through `scrollToTopSelectors` and retains precedence over stale window positions through destination invalidations.
+
+Scroll positions are sampled when leaving a route, preserving live changes made after the most recent scroll event. This also prevents client hydration from undoing nested positions restored by the SSR script.
+
+Fixes #7687.

e2e/react-start/scroll-restoration/src/routeTree.gen.ts

@@ -21,8 +21,11 @@ import { Route as testsNestedScrollSearchRouteImport } from './routes/(tests)/ne
 import { Route as testsNestedScrollCarryOverBRouteImport } from './routes/(tests)/nested-scroll-carry-over-b'
 import { Route as testsNestedScrollCarryOverARouteImport } from './routes/(tests)/nested-scroll-carry-over-a'
 import { Route as testsNestedScrollAwayRouteImport } from './routes/(tests)/nested-scroll-away'
+import { Route as testsIssue7687RouteImport } from './routes/(tests)/issue-7687'
 import { Route as testsHashScrollReproRouteImport } from './routes/(tests)/hash-scroll-repro'
 import { Route as testsHashScrollAboutRouteImport } from './routes/(tests)/hash-scroll-about'
+import { Route as testsIssue7687IndexRouteImport } from './routes/(tests)/issue-7687.index'
+import { Route as testsIssue7687DetailRouteImport } from './routes/(tests)/issue-7687.detail'
 
 const IndexRoute = IndexRouteImport.update({
   id: '/',
@@ -86,6 +89,11 @@ const testsNestedScrollAwayRoute = testsNestedScrollAwayRouteImport.update({
   path: '/nested-scroll-away',
   getParentRoute: () => rootRouteImport,
 } as any)
+const testsIssue7687Route = testsIssue7687RouteImport.update({
+  id: '/(tests)/issue-7687',
+  path: '/issue-7687',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const testsHashScrollReproRoute = testsHashScrollReproRouteImport.update({
   id: '/(tests)/hash-scroll-repro',
   path: '/hash-scroll-repro',
@@ -96,11 +104,22 @@ const testsHashScrollAboutRoute = testsHashScrollAboutRouteImport.update({
   path: '/hash-scroll-about',
   getParentRoute: () => rootRouteImport,
 } as any)
+const testsIssue7687IndexRoute = testsIssue7687IndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => testsIssue7687Route,
+} as any)
+const testsIssue7687DetailRoute = testsIssue7687DetailRouteImport.update({
+  id: '/detail',
+  path: '/detail',
+  getParentRoute: () => testsIssue7687Route,
+} as any)
 
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
   '/hash-scroll-about': typeof testsHashScrollAboutRoute
   '/hash-scroll-repro': typeof testsHashScrollReproRoute
+  '/issue-7687': typeof testsIssue7687RouteWithChildren
   '/nested-scroll-away': typeof testsNestedScrollAwayRoute
   '/nested-scroll-carry-over-a': typeof testsNestedScrollCarryOverARoute
   '/nested-scroll-carry-over-b': typeof testsNestedScrollCarryOverBRoute
@@ -112,6 +131,8 @@ export interface FileRoutesByFullPath {
   '/ssr-scroll-key': typeof testsSsrScrollKeyRoute
   '/with-loader': typeof testsWithLoaderRoute
   '/with-search': typeof testsWithSearchRoute
+  '/issue-7687/detail': typeof testsIssue7687DetailRoute
+  '/issue-7687/': typeof testsIssue7687IndexRoute
 }
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
@@ -128,12 +149,15 @@ export interface FileRoutesByTo {
   '/ssr-scroll-key': typeof testsSsrScrollKeyRoute
   '/with-loader': typeof testsWithLoaderRoute
   '/with-search': typeof testsWithSearchRoute
+  '/issue-7687/detail': typeof testsIssue7687DetailRoute
+  '/issue-7687': typeof testsIssue7687IndexRoute
 }
 export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/': typeof IndexRoute
   '/(tests)/hash-scroll-about': typeof testsHashScrollAboutRoute
   '/(tests)/hash-scroll-repro': typeof testsHashScrollReproRoute
+  '/(tests)/issue-7687': typeof testsIssue7687RouteWithChildren
   '/(tests)/nested-scroll-away': typeof testsNestedScrollAwayRoute
   '/(tests)/nested-scroll-carry-over-a': typeof testsNestedScrollCarryOverARoute
   '/(tests)/nested-scroll-carry-over-b': typeof testsNestedScrollCarryOverBRoute
@@ -145,13 +169,16 @@ export interface FileRoutesById {
   '/(tests)/ssr-scroll-key': typeof testsSsrScrollKeyRoute
   '/(tests)/with-loader': typeof testsWithLoaderRoute
   '/(tests)/with-search': typeof testsWithSearchRoute
+  '/(tests)/issue-7687/detail': typeof testsIssue7687DetailRoute
+  '/(tests)/issue-7687/': typeof testsIssue7687IndexRoute
 }
 export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
   fullPaths:
     | '/'
     | '/hash-scroll-about'
     | '/hash-scroll-repro'
+    | '/issue-7687'
     | '/nested-scroll-away'
     | '/nested-scroll-carry-over-a'
     | '/nested-scroll-carry-over-b'
@@ -163,6 +190,8 @@ export interface FileRouteTypes {
     | '/ssr-scroll-key'
     | '/with-loader'
     | '/with-search'
+    | '/issue-7687/detail'
+    | '/issue-7687/'
   fileRoutesByTo: FileRoutesByTo
   to:
     | '/'
@@ -179,11 +208,14 @@ export interface FileRouteTypes {
     | '/ssr-scroll-key'
     | '/with-loader'
     | '/with-search'
+    | '/issue-7687/detail'
+    | '/issue-7687'
   id:
     | '__root__'
     | '/'
     | '/(tests)/hash-scroll-about'
     | '/(tests)/hash-scroll-repro'
+    | '/(tests)/issue-7687'
     | '/(tests)/nested-scroll-away'
     | '/(tests)/nested-scroll-carry-over-a'
     | '/(tests)/nested-scroll-carry-over-b'
@@ -195,12 +227,15 @@ export interface FileRouteTypes {
     | '/(tests)/ssr-scroll-key'
     | '/(tests)/with-loader'
     | '/(tests)/with-search'
+    | '/(tests)/issue-7687/detail'
+    | '/(tests)/issue-7687/'
   fileRoutesById: FileRoutesById
 }
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
   testsHashScrollAboutRoute: typeof testsHashScrollAboutRoute
   testsHashScrollReproRoute: typeof testsHashScrollReproRoute
+  testsIssue7687Route: typeof testsIssue7687RouteWithChildren
   testsNestedScrollAwayRoute: typeof testsNestedScrollAwayRoute
   testsNestedScrollCarryOverARoute: typeof testsNestedScrollCarryOverARoute
   testsNestedScrollCarryOverBRoute: typeof testsNestedScrollCarryOverBRoute
@@ -300,6 +335,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof testsNestedScrollAwayRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/(tests)/issue-7687': {
+      id: '/(tests)/issue-7687'
+      path: '/issue-7687'
+      fullPath: '/issue-7687'
+      preLoaderRoute: typeof testsIssue7687RouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/(tests)/hash-scroll-repro': {
       id: '/(tests)/hash-scroll-repro'
       path: '/hash-scroll-repro'
@@ -314,13 +356,42 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof testsHashScrollAboutRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/(tests)/issue-7687/': {
+      id: '/(tests)/issue-7687/'
+      path: '/'
+      fullPath: '/issue-7687/'
+      preLoaderRoute: typeof testsIssue7687IndexRouteImport
+      parentRoute: typeof testsIssue7687Route
+    }
+    '/(tests)/issue-7687/detail': {
+      id: '/(tests)/issue-7687/detail'
+      path: '/detail'
+      fullPath: '/issue-7687/detail'
+      preLoaderRoute: typeof testsIssue7687DetailRouteImport
+      parentRoute: typeof testsIssue7687Route
+    }
   }
 }
 
+interface testsIssue7687RouteChildren {
+  testsIssue7687DetailRoute: typeof testsIssue7687DetailRoute
+  testsIssue7687IndexRoute: typeof testsIssue7687IndexRoute
+}
+
+const testsIssue7687RouteChildren: testsIssue7687RouteChildren = {
+  testsIssue7687DetailRoute: testsIssue7687DetailRoute,
+  testsIssue7687IndexRoute: testsIssue7687IndexRoute,
+}
+
+const testsIssue7687RouteWithChildren = testsIssue7687Route._addFileChildren(
+  testsIssue7687RouteChildren,
+)
+
 const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
   testsHashScrollAboutRoute: testsHashScrollAboutRoute,
   testsHashScrollReproRoute: testsHashScrollReproRoute,
+  testsIssue7687Route: testsIssue7687RouteWithChildren,
   testsNestedScrollAwayRoute: testsNestedScrollAwayRoute,
   testsNestedScrollCarryOverARoute: testsNestedScrollCarryOverARoute,
   testsNestedScrollCarryOverBRoute: testsNestedScrollCarryOverBRoute,

e2e/react-start/scroll-restoration/src/router.tsx

@@ -7,13 +7,32 @@ export function getRouter() {
   const router = createRouter({
     routeTree,
     scrollRestoration: true,
-    scrollToTopSelectors: ['[data-scroll-restoration-id="carry-over-reset"]'],
+    scrollToTopSelectors: [
+      '[data-scroll-restoration-id="carry-over-reset"]',
+      '#hash-scroll-nested',
+      '#hash-scroll-reset-target',
+      '#issue-7687-reset-probe',
+      '#issue-7687-scroller',
+      () =>
+        typeof document === 'undefined'
+          ? undefined
+          : document.getElementById('issue-7687-stale-selector'),
+      '#ssr-scroll-key-nested',
+    ],
     getScrollRestorationKey: (location) => {
       if (location.pathname === '/ssr-scroll-key') {
         return 'ssr-scroll-key'
       }
 
       if (location.pathname === '/hash-scroll-repro') {
+        const scrollKey =
+          'scrollKey' in location.search ? location.search.scrollKey : undefined
+        return typeof scrollKey === 'string'
+          ? `${location.pathname}:${scrollKey}`
+          : location.pathname
+      }
+
+      if (location.pathname.startsWith('/issue-7687')) {
         return location.pathname
       }
 

e2e/react-start/scroll-restoration/src/routes/(tests)/hash-scroll-about.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react'
-import { createFileRoute } from '@tanstack/react-router'
+import { Link, createFileRoute } from '@tanstack/react-router'
 import { sleep } from '~/utils/posts'
 
 export const Route = createFileRoute('/(tests)/hash-scroll-about')({
@@ -17,6 +17,20 @@ function Component() {
       <p data-testid="hash-scroll-about-top">
         This route exists so hover preloading can reproduce the hash scroll bug.
       </p>
+      <Link
+        to="/hash-scroll-repro"
+        hash="one"
+        data-testid="hash-scroll-restore-link"
+      >
+        Return to #one
+      </Link>
+      <Link
+        to="/hash-scroll-repro"
+        search={{ scrollKey: 'destination' }}
+        data-testid="hash-scroll-destination-link"
+      >
+        Return to the destination key
+      </Link>
     </div>
   )
 }

e2e/react-start/scroll-restoration/src/routes/(tests)/hash-scroll-repro.tsx

@@ -1,8 +1,13 @@
 import * as React from 'react'
 import { Link, createFileRoute, useRouter } from '@tanstack/react-router'
+import { z } from 'zod'
 import { sleep } from '~/utils/posts'
 
 export const Route = createFileRoute('/(tests)/hash-scroll-repro')({
+  validateSearch: z.object({
+    scrollKey: z.string().optional(),
+    invalidateOnMount: z.boolean().optional(),
+  }),
   loader: async () => {
     await sleep(50)
     return null
@@ -14,7 +19,20 @@ const sectionIds = ['one', 'two', 'three', 'four', 'five'] as const
 
 function Component() {
   const router = useRouter()
+  const { invalidateOnMount } = Route.useSearch()
   const [invalidateCount, setInvalidateCount] = React.useState(0)
+  const invalidatedOnMount = React.useRef(false)
+
+  React.useLayoutEffect(() => {
+    if (!invalidateOnMount || invalidatedOnMount.current) {
+      return
+    }
+
+    invalidatedOnMount.current = true
+    void router.invalidate().then(() => {
+      setInvalidateCount((count) => count + 1)
+    })
+  }, [invalidateOnMount, router])
 
   return (
     <div className="p-2">
@@ -61,6 +79,24 @@ function Component() {
           >
             #four no reset
           </Link>
+          <Link
+            to="/hash-scroll-repro"
+            search={{ scrollKey: 'destination' }}
+            hash="one"
+            className="rounded border px-3 py-2"
+            data-testid="hash-scroll-different-key-link"
+          >
+            #one different key
+          </Link>
+          <Link
+            to="/hash-scroll-repro"
+            search={{ invalidateOnMount: true }}
+            hash="one"
+            className="rounded border px-3 py-2"
+            data-testid="hash-scroll-layout-invalidate-link"
+          >
+            #one and invalidate in layout effect
+          </Link>
         </div>
       </div>
 
@@ -74,6 +110,16 @@ function Component() {
         ))}
       </div>
 
+      <div
+        id="hash-scroll-reset-target"
+        data-testid="hash-scroll-reset-target"
+        className="mt-4 h-24 overflow-auto rounded border p-2"
+      >
+        {Array.from({ length: 20 }).map((_, i) => (
+          <div key={i}>Hash reset target row {i}</div>
+        ))}
+      </div>
+
       <div className="mt-6 grid gap-10">
         {sectionIds.map((sectionId) => (
           <section

e2e/react-start/scroll-restoration/src/routes/(tests)/issue-7687.detail.tsx

@@ -0,0 +1,16 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/(tests)/issue-7687/detail')({
+  component: Component,
+})
+
+function Component() {
+  return (
+    <div className="grid gap-4">
+      <h3>issue-7687-detail</h3>
+      {Array.from({ length: 40 }).map((_, i) => (
+        <div key={i}>Detail row {i}</div>
+      ))}
+    </div>
+  )
+}