diff --git a/docs/framework/react/guide/scroll-restoration.md b/docs/framework/react/guide/scroll-restoration.md
index 2f53c0519e..7b56faa245 100644
--- a/docs/framework/react/guide/scroll-restoration.md
+++ b/docs/framework/react/guide/scroll-restoration.md
@@ -137,3 +137,20 @@ function Component() {
)
}
```
+
+## Scroll Behavior
+
+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'
+
+function Root() {
+ return (
+ <>
+
+
+ >
+ )
+}
+```
diff --git a/packages/react-router/src/scroll-restoration.tsx b/packages/react-router/src/scroll-restoration.tsx
index 26a3861e90..6d764bebcf 100644
--- a/packages/react-router/src/scroll-restoration.tsx
+++ b/packages/react-router/src/scroll-restoration.tsx
@@ -45,6 +45,7 @@ const cache: Cache = sessionsStorage
export type ScrollRestorationOptions = {
getKey?: (location: ParsedLocation) => string
+ scrollBehavior?: ScrollToOptions['behavior']
}
/**
@@ -154,7 +155,11 @@ export function useScrollRestoration(options?: ScrollRestorationOptions) {
if (key === restoreKey) {
if (elementSelector === windowKey) {
windowRestored = true
- window.scrollTo(entry.scrollX, entry.scrollY)
+ window.scrollTo({
+ top: entry.scrollY,
+ left: entry.scrollX,
+ behavior: options?.scrollBehavior,
+ })
} else if (elementSelector) {
const element = document.querySelector(elementSelector)
if (element) {