feat: scrollRestorationBehavior per navigation

Author: schiller-manuel

packages/history/src/index.ts

@@ -72,6 +72,8 @@ export type ParsedHistoryState = HistoryState & {
   __TSR_index: number
   /** Whether to reset scroll position on this navigation (default: true) */
   __TSR_resetScroll?: boolean
+  /** Scroll restoration behavior override for this navigation */
+  __TSR_scrollRestorationBehavior?: ScrollBehavior
   /** Session id for cached TSR internals */
   __TSR_sessionId?: string
   /** Match snapshot for fast-path on back/forward navigation */

packages/router-core/src/RouterProvider.ts

@@ -20,6 +20,7 @@ export interface CommitLocationOptions {
    **/
   startTransition?: boolean
   ignoreBlocker?: boolean
+  scrollRestorationBehavior?: ScrollBehavior
 }
 
 export type NavigateFn = <

packages/router-core/src/link.ts

@@ -348,6 +348,12 @@ export interface NavigateOptionProps {
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/NavigateOptionsType#reloaddocument)
    */
   reloadDocument?: boolean
+  /**
+   * The scroll behavior to use for scroll restoration on this navigation.
+   * If provided, this will override `router.options.scrollRestorationBehavior` for this navigation only.
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/NavigateOptionsType#scrollrestorationbehavior)
+   */
+  scrollRestorationBehavior?: ScrollBehavior
   /**
    * This can be used instead of `to` to navigate to a fully built href, e.g. pointing to an external target.
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/NavigateOptionsType#href)

packages/router-core/src/router.ts

@@ -1960,6 +1960,7 @@ export class RouterCore<
   commitLocation: CommitLocationFn = async ({
     viewTransition,
     ignoreBlocker,
+    scrollRestorationBehavior,
     ...next
   }) => {
     const isSameState = () => {
@@ -2035,6 +2036,10 @@ export class RouterCore<
     nextHistory.state.__hashScrollIntoViewOptions =
       hashScrollIntoView ?? this.options.defaultHashScrollIntoView ?? true
 
+    // Store scrollRestorationBehavior in history state so it survives back/forward navigation
+    nextHistory.state.__TSR_scrollRestorationBehavior =
+      scrollRestorationBehavior
+
     // Store resetScroll in history state so it survives back/forward navigation
     nextHistory.state.__TSR_resetScroll = next.resetScroll ?? true
 
@@ -2102,6 +2107,7 @@ export class RouterCore<
     hashScrollIntoView,
     viewTransition,
     ignoreBlocker,
+    scrollRestorationBehavior,
     href,
     ...rest
   }: BuildNextOptions & CommitLocationOptions = {}) => {
@@ -2140,6 +2146,7 @@ export class RouterCore<
       resetScroll,
       hashScrollIntoView,
       ignoreBlocker,
+      scrollRestorationBehavior,
     })
 
     // Clear pending location after commit starts

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

@@ -356,7 +356,9 @@ export function setupScrollRestoration(router: AnyRouter, force?: boolean) {
     restoreScroll({
       storageKey,
       key: cacheKey,
-      behavior: router.options.scrollRestorationBehavior,
+      behavior:
+        event.toLocation.state.__TSR_scrollRestorationBehavior ??
+        router.options.scrollRestorationBehavior,
       shouldScrollRestoration: router.isScrollRestoring,
       scrollToTopSelectors: router.options.scrollToTopSelectors,
       location: router.history.location,