From bc085acf54e164763164c206ffcde45a0038719f Mon Sep 17 00:00:00 2001
From: Darrel <128795218+darreleng@users.noreply.github.com>
Date: Sun, 7 Jun 2026 18:21:56 +0800
Subject: [PATCH 1/2] docs: add scroll restoration options to RouterOptionsType

Noticed that the entire suite of scroll restoration configurations (scrollRestoration, getScrollRestorationKey, scrollRestorationBehavior, and scrollToTopSelectors) present in router.d.ts were completely undocumented on the RouterOptionsType page. Added documentation for all four properties using the docstrings in router.ts plus links to the existing scroll restoration guide.
---
 docs/router/api/router/RouterOptionsType.md | 38 +++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/docs/router/api/router/RouterOptionsType.md b/docs/router/api/router/RouterOptionsType.md
index 7127e1191e..c9f08956e2 100644
--- a/docs/router/api/router/RouterOptionsType.md
+++ b/docs/router/api/router/RouterOptionsType.md
@@ -411,3 +411,41 @@ If you want to configure to remount all route components upon `params` change, u
 ```tsx
 remountDeps: ({ params }) => params
 ```
+
+### `scrollRestoration` property
+
+- Type: `boolean | ((opts: { location: ParsedLocation }) => boolean)`
+- Optional
+- Defaults to `false`
+- If `true`, scroll restoration will be enabled.
+- See the [Scroll Restoration Guide](../../guide/scroll-restoration.md/#scroll-restoration) for more information.
+
+---
+
+### `getScrollRestorationKey` property
+
+- Type: `(location: ParsedLocation) => string`
+- Optional
+- Defaults to `(location) => location.href`
+- A function that will be called to get the key for the scroll restoration cache.
+- See the [Scroll Restoration Guide](../../guide/scroll-restoration.md/#custom-cache-keys) for more information.
+
+---
+
+### `scrollRestorationBehavior` property
+
+- Type: `ScrollBehavior` (e.g., `'auto' | 'smooth'`)
+- Optional
+- Defaults to `'auto'`
+- The default behavior for scroll restoration.
+- See the [Scroll Restoration Guide](../../guide/scroll-restoration.md/#scroll-behavior) for more information.
+
+---
+
+### `scrollToTopSelectors` property
+
+- Type: `Array<string | (() => Element | null | undefined)>`
+- Optional
+- Defaults to `['window']`
+- An array of selectors that will be used to scroll to the top of the page in addition to `window`.
+- See the [Scroll Restoration Guide](../../guide/scroll-restoration.md/#hashtop-of-page-scrolling) for more information.

From 49bc8d7703d2d8c49c26233c980ae187701a1374 Mon Sep 17 00:00:00 2001
From: Darrel <128795218+darreleng@users.noreply.github.com>
Date: Sun, 7 Jun 2026 18:32:52 +0800
Subject: [PATCH 2/2] docs: add @links to scroll properties docstrings

Added documentation links for scroll restoration options.
---
 packages/router-core/src/router.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/packages/router-core/src/router.ts b/packages/router-core/src/router.ts
index c11cc86082..bc02db24e6 100644
--- a/packages/router-core/src/router.ts
+++ b/packages/router-core/src/router.ts
@@ -453,6 +453,7 @@ export interface RouterOptions<
    * If `true`, scroll restoration will be enabled
    *
    * @default false
+   * @link [Guide](https://tanstack.com/router/v1/docs/guide/scroll-restoration#scroll-restoration)
    */
   scrollRestoration?:
     | boolean
@@ -462,18 +463,21 @@ export interface RouterOptions<
    * A function that will be called to get the key for the scroll restoration cache.
    *
    * @default (location) => location.href
+   * @link [Guide](https://tanstack.com/router/v1/docs/guide/scroll-restoration#custom-cache-keys)
    */
   getScrollRestorationKey?: (location: ParsedLocation) => string
   /**
    * The default behavior for scroll restoration.
    *
    * @default 'auto'
+   * @link [Guide](https://tanstack.com/router/v1/docs/guide/scroll-restoration#scroll-behavior)
    */
   scrollRestorationBehavior?: ScrollBehavior
   /**
    * An array of selectors that will be used to scroll to the top of the page in addition to `window`
    *
    * @default ['window']
+   * @link [Guide](https://tanstack.com/router/v1/docs/guide/scroll-restoration#hashtop-of-page-scrolling)
    */
   scrollToTopSelectors?: Array<string | (() => Element | null | undefined)>