> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/remix-run/react-router/llms.txt
> Use this file to discover all available pages before exploring further.
# useScrollRestoration
# `useScrollRestoration`
This hook is deprecated. Use the `` component instead.
When rendered inside a `RouterProvider`, will restore scroll positions on navigations.
```tsx theme={null}
import { useScrollRestoration } from "react-router";
function App() {
useScrollRestoration();
return
{/* Your app */}
;
}
```
## Parameters
A function that returns a key to use for scroll restoration. This is useful for custom scroll restoration logic, such as using only the pathname so that subsequent navigations to prior paths will restore the scroll.
Defaults to `location.key`.
```tsx theme={null}
useScrollRestoration({
getKey: (location, matches) => {
// Restore based on pathname only
return location.pathname;
},
});
```
The key to use for storing scroll positions in `sessionStorage`.
## Type Declaration
```tsx theme={null}
declare function useScrollRestoration(options?: {
getKey?: GetScrollRestorationKeyFunction;
storageKey?: string;
}): void;
type GetScrollRestorationKeyFunction = (
location: Location,
matches: UIMatch[]
) => string | null;
```
## Deprecation Notice
This hook is deprecated in favor of the `` component. The component approach is preferred because:
1. **Better SSR support**: The component can inject the necessary script for SSR scroll restoration
2. **Simpler API**: No need to manually call the hook in your components
3. **Automatic setup**: Just render the component and it works
### Migration Guide
#### Before (using useScrollRestoration)
```tsx theme={null}
import { useScrollRestoration } from "react-router";
function Root() {
useScrollRestoration();
return (
);
}
```
#### After (using ScrollRestoration component)
```tsx theme={null}
import { ScrollRestoration } from "react-router";
export default function Root() {
return (
);
}
```
## Usage Examples (Legacy)
### Basic Usage
```tsx theme={null}
import { useScrollRestoration } from "react-router";
function App() {
useScrollRestoration();
return (
;
}
```
### Pathname-Based Restoration
```tsx theme={null}
import { useScrollRestoration } from "react-router";
function App() {
useScrollRestoration({
getKey: (location, matches) => {
// Restore scroll based only on pathname
// This means going to /blog/post-1 will always
// restore to the same position, regardless of how you got there
return location.pathname;
},
});
return
{/* App content */}
;
}
```
### Route-Based Restoration
```tsx theme={null}
import { useScrollRestoration } from "react-router";
function App() {
useScrollRestoration({
getKey: (location, matches) => {
// Restore based on the route ID
const match = matches[matches.length - 1];
return match?.route.id || location.key;
},
});
return
;
}
```
## How It Works
The hook:
1. **Saves scroll positions** to `sessionStorage` when navigating away from a page
2. **Restores scroll positions** when navigating back to a previously visited page
3. **Uses `location.key`** by default to track scroll positions for each history entry
4. **Allows customization** via the `getKey` function for different restoration strategies
## Alternatives
### Use ScrollRestoration Component (Recommended)
```tsx theme={null}
import { ScrollRestoration } from "react-router";
export default function Root() {
return (
);
}
```
### Manual Scroll Management
```tsx theme={null}
import { useEffect } from "react";
import { useLocation } from "react-router";
function App() {
const location = useLocation();
useEffect(() => {
// Custom scroll behavior
window.scrollTo(0, 0);
}, [location.pathname]);
return
{/* App content */}
;
}
```
### Prevent Scroll Reset on Specific Links
```tsx theme={null}
import { Link } from "react-router";
Don't reset scroll
```
## Notes
* **Deprecated**: Use the `` component instead
* Available in Framework and Data modes only
* Must be used within a `RouterProvider`
* Stores scroll positions in `sessionStorage`
* The `getKey` function allows customizing which navigations restore scroll
* Returning `null` from `getKey` prevents scroll restoration for that navigation
## Related
* [``](/api/components/scroll-restoration) - Recommended replacement component
* [`preventScrollReset`](/api/components/link#preventscrollreset) - Prevent scroll reset on specific navigations
* [`useLocation`](/api/hooks/use-location) - Get current location
* [Scroll Restoration Guide](/how-to/scroll-restoration) - Learn about scroll restoration patterns