Skip to content

docs: add missing scroll restoration properties to RouterOptionsType.md and link to the official scroll restoration guide to their docstrings #7574

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
darreleng wants to merge 2 commits into
base: main
Choose a base branch
from
+42 −0
Open

docs: add missing scroll restoration properties to RouterOptionsType.md and link to the official scroll restoration guide to their docstrings #7574

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bc085ac
docs: add scroll restoration options to RouterOptionsType
darreleng Jun 7, 2026
49bc8d7
docs: add @links to scroll properties docstrings
darreleng Jun 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions docs/router/api/router/RouterOptionsType.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

@coderabbitai coderabbitai Bot Jun 7, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix malformed internal scroll-restoration links (.md/#...).

These links include an extra / before the hash fragment, which can break internal doc navigation. Use ../../guide/scroll-restoration.md#... instead.

Suggested patch 
-- See the [Scroll Restoration Guide](../../guide/scroll-restoration.md/#scroll-restoration) for more information.
+- See the [Scroll Restoration Guide](../../guide/scroll-restoration.md#scroll-restoration) for more information.
...
-- See the [Scroll Restoration Guide](../../guide/scroll-restoration.md/#custom-cache-keys) for more information.
+- See the [Scroll Restoration Guide](../../guide/scroll-restoration.md#custom-cache-keys) for more information.
...
-- See the [Scroll Restoration Guide](../../guide/scroll-restoration.md/#scroll-behavior) for more information.
+- See the [Scroll Restoration Guide](../../guide/scroll-restoration.md#scroll-behavior) for more information.
...
-- See the [Scroll Restoration Guide](../../guide/scroll-restoration.md/#hashtop-of-page-scrolling) for more information.
+- See the [Scroll Restoration Guide](../../guide/scroll-restoration.md#hashtop-of-page-scrolling) for more information.

Based on learnings and coding guidelines, docs/router links should remain file-relative and correctly formed for internal navigation.

Also applies to: 431-431, 441-441, 451-451

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/router/api/router/RouterOptionsType.md` at line 421, Update the
malformed internal links to the Scroll Restoration Guide by removing the extra
slash before the fragment: replace occurrences of
"../../guide/scroll-restoration.md/#scroll-restoration" (and similar links
referenced near the "Scroll Restoration Guide" link text) with
"../../guide/scroll-restoration.md#scroll-restoration" in the
RouterOptionsType.md file (also fix the same pattern at the other reported
occurrences).

Sources: Coding guidelines, Learnings


---

### `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.
4 changes: 4 additions & 0 deletions packages/router-core/src/router.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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)>

Expand Down