fix: Fix scroll restoration

README.md

@@ -78,4 +78,4 @@ Enjoy this library? Try the entire [TanStack](https://tanstack.com)! [React Quer
 
 To run example React projects with Tanstack Router, see [CONTRIBUTING.md](./CONTRIBUTING.md)
 
-<!-- Use the force, Luke! -->
+<!-- Use the force, Luke!! -->

docs/eslint/create-route-property-order.md

@@ -17,7 +17,7 @@ The correct property order is as follows
 - `context`
 - `beforeLoad`
 - `loader`
-- `onEnter`, `onStay`, `onLeave`, `meta`, `links`, `scripts`, `headers`
+- `onEnter`, `onStay`, `onLeave`, `meta`, `links`, `scripts`, `headers`, `remountDeps`
 
 All other properties are insensitive to the order as they do not depend on type inference.
 

docs/framework/react/api/router/RouteOptionsType.md

@@ -266,3 +266,35 @@ type loaderDeps = (opts: { search: TFullSearchSchema }) => Record<string, any>
 - Type: `(error: Error, errorInfo: ErrorInfo) => void`
 - Optional - Defaults to `routerOptions.defaultOnCatch`
 - A function that will be called when errors are caught when the route encounters an error.
+
+### `remountDeps` method
+
+- Type:
+
+```tsx
+type remountDeps = (opts: RemountDepsOptions) => any
+
+interface RemountDepsOptions<
+  in out TRouteId,
+  in out TFullSearchSchema,
+  in out TAllParams,
+  in out TLoaderDeps,
+> {
+  routeId: TRouteId
+  search: TFullSearchSchema
+  params: TAllParams
+  loaderDeps: TLoaderDeps
+}
+```
+
+- Optional
+- A function that will be called to determine whether a route component shall be remounted after navigation. If this function returns a different value than previously, it will remount.
+- The return value needs to be JSON serializable.
+- By default, a route component will not be remounted if it stays active after a navigation
+
+Example:  
+If you want to configure to remount a route component upon `params` change, use:
+
+```tsx
+remountDeps: ({ params }) => params
+```

docs/framework/react/api/router/RouterEventsType.md

@@ -9,39 +9,48 @@ The `RouterEvents` type contains all of the events that the router can emit. Eac
 type RouterEvents = {
   onBeforeNavigate: {
     type: 'onBeforeNavigate'
-    fromLocation: ParsedLocation
+    fromLocation?: ParsedLocation
     toLocation: ParsedLocation
     pathChanged: boolean
     hrefChanged: boolean
   }
   onBeforeLoad: {
     type: 'onBeforeLoad'
-    fromLocation: ParsedLocation
+    fromLocation?: ParsedLocation
     toLocation: ParsedLocation
     pathChanged: boolean
     hrefChanged: boolean
   }
   onLoad: {
     type: 'onLoad'
-    fromLocation: ParsedLocation
+    fromLocation?: ParsedLocation
     toLocation: ParsedLocation
     pathChanged: boolean
     hrefChanged: boolean
   }
   onResolved: {
     type: 'onResolved'
-    fromLocation: ParsedLocation
+    fromLocation?: ParsedLocation
     toLocation: ParsedLocation
     pathChanged: boolean
     hrefChanged: boolean
   }
   onBeforeRouteMount: {
     type: 'onBeforeRouteMount'
-    fromLocation: ParsedLocation
+    fromLocation?: ParsedLocation
     toLocation: ParsedLocation
     pathChanged: boolean
     hrefChanged: boolean
   }
+  onInjectedHtml: {
+    type: 'onInjectedHtml'
+    promise: Promise<string>
+  }
+  onRendered: {
+    type: 'onRendered'
+    fromLocation?: ParsedLocation
+    toLocation: ParsedLocation
+  }
 }
 ```
 

docs/framework/react/api/router/RouterOptionsType.md

@@ -296,3 +296,35 @@ const router = createRouter({
 - Defaults to `false`
 - Configures whether structural sharing is enabled by default for fine-grained selectors.
 - See the [Render Optimizations guide](../../guide/render-optimizations.md) for more information.
+
+### `defaultRemountDeps` property
+
+- Type:
+
+```tsx
+type defaultRemountDeps = (opts: RemountDepsOptions) => any
+
+interface RemountDepsOptions<
+  in out TRouteId,
+  in out TFullSearchSchema,
+  in out TAllParams,
+  in out TLoaderDeps,
+> {
+  routeId: TRouteId
+  search: TFullSearchSchema
+  params: TAllParams
+  loaderDeps: TLoaderDeps
+}
+```
+
+- Optional
+- A default function that will be called to determine whether a route component shall be remounted after navigation. If this function returns a different value than previously, it will remount.
+- The return value needs to be JSON serializable.
+- By default, a route component will not be remounted if it stays active after a navigation
+
+Example:  
+If you want to configure to remount all route components upon `params` change, use:
+
+```tsx
+remountDeps: ({ params }) => params
+```

docs/framework/react/comparison.md

@@ -57,6 +57,8 @@ Feature/Capability Key:
 | `<Block>`/`useBlocker`                         | ✅                                               | 🔶                                                    | ❓                                                    |
 | Deferred Primitives                            | ✅                                               | ✅                                                    | ✅                                                    |
 | Navigation Scroll Restoration                  | ✅                                               | ✅                                                    | ❓                                                    |
+| ElementScroll Restoration                      | ✅                                               | 🛑                                                    | 🛑                                                    |
+| Async Scroll Restoration                       | ✅                                               | 🛑                                                    | 🛑                                                    |
 | Router Invalidation                            | ✅                                               | ✅                                                    | ✅                                                    |
 | Runtime Route Manipulation (Fog of War)        | 🛑                                               | ✅                                                    | ✅                                                    |
 | --                                             | --                                               | --                                                    | --                                                    |

docs/framework/react/guide/scroll-restoration.md

@@ -3,6 +3,12 @@ id: scroll-restoration
 title: Scroll Restoration
 ---
 
+## Hash/Top-of-Page Scrolling
+
+Out of the box, TanStack Router supports both **hash scrolling** and **top-of-page scrolling** without any additional configuration.
+
+## Scroll Restoration
+
 Scroll restoration is the process of restoring the scroll position of a page when the user navigates back to it. This is normally a built-in feature for standard HTML based websites, but can be difficult to replicate for SPA applications because:
 
 - SPAs typically use the `history.pushState` API for navigation, so the browser doesn't know to restore the scroll position natively
@@ -24,19 +30,15 @@ It does this by:
 That may sound like a lot, but for you, it's as simple as this:
 
 ```tsx
-import { ScrollRestoration } from '@tanstack/react-router'
+import { createRouter } from '@tanstack/react-router'
 
-function Root() {
-  return (
-    <>
-      <ScrollRestoration />
-      <Outlet />
-    </>
-  )
-}
+const router = createRouter({
+  scrollRestoration: true,
+})
 ```
 
-Just render the `ScrollRestoration` component (or use the `useScrollRestoration` hook) at the root of your application and it will handle everything automatically!
+> [!NOTE]
+> The `<ScrollRestoration />` component still works, but has been deprecated.
 
 ## Custom Cache Keys
 
@@ -51,38 +53,26 @@ The default `getKey` is `(location) => location.state.key!`, where `key` is the
 You could sync scrolling to the pathname:
 
 ```tsx
-import { ScrollRestoration } from '@tanstack/react-router'
+import { createRouter } from '@tanstack/react-router'
 
-function Root() {
-  return (
-    <>
-      <ScrollRestoration getKey={(location) => location.pathname} />
-      <Outlet />
-    </>
-  )
-}
+const router = createRouter({
+  getScrollRestorationKey: (location) => location.pathname,
+})
 ```
 
 You can conditionally sync only some paths, then use the key for the rest:
 
 ```tsx
-import { ScrollRestoration } from '@tanstack/react-router'
-
-function Root() {
-  return (
-    <>
-      <ScrollRestoration
-        getKey={(location) => {
-          const paths = ['/', '/chat']
-          return paths.includes(location.pathname)
-            ? location.pathname
-            : location.state.key!
-        }}
-      />
-      <Outlet />
-    </>
-  )
-}
+import { createRouter } from '@tanstack/react-router'
+
+const router = createRouter({
+  getScrollRestorationKey: (location) => {
+    const paths = ['/', '/chat']
+    return paths.includes(location.pathname)
+      ? location.pathname
+      : location.state.key!
+  },
+})
 ```
 
 ## Preventing Scroll Restoration
@@ -143,14 +133,9 @@ function Component() {
 To control the scroll behavior when navigating between pages, you can use the `scrollBehavior` option. This allows you to make the transition between pages instant instead of a smooth scroll. The global configuration of scroll restoration behavior has the same options as those supported by the browser, which are `smooth`, `instant`, and `auto` (see [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView#behavior) for more information).
 
 ```tsx
-import { ScrollRestoration } from '@tanstack/react-router'
+import { createRouter } from '@tanstack/react-router'
 
-function Root() {
-  return (
-    <>
-      <ScrollRestoration scrollBehavior="instant" />
-      <Outlet />
-    </>
-  )
-}
+const router = createRouter({
+  scrollBehavior: 'instant',
+})
 ```

e2e/react-router/basic-scroll-restoration/src/main.tsx

@@ -12,7 +12,6 @@ import {
 } from '@tanstack/react-router'
 import { TanStackRouterDevtools } from '@tanstack/router-devtools'
 import { useVirtualizer } from '@tanstack/react-virtual'
-import HasShown from './has-shown'
 import './styles.css'
 
 const rootRoute = createRootRoute({
@@ -60,7 +59,7 @@ function IndexComponent() {
       <h3 id="greeting" className="bg-red-600">
         Welcome Home!
       </h3>
-      <HasShown id="top-message" />
+      <div id="top-message" />
       <div className="space-y-2">
         {Array.from({ length: 50 }).map((_, i) => (
           <div
@@ -141,7 +140,7 @@ function ByElementComponent() {
         >
           <div className="h-[100px] p-2 rounded-lg bg-red-600 border">
             First Regular List Item
-            <HasShown id="first-regular-list-item" />
+            <div id="first-regular-list-item" />
           </div>
           {Array.from({ length: 50 }).map((_, i) => (
             <div