ScrollRestoration

Emulates the browser’s scroll restoration on location changes. Apps should only render one of these, right before the <Scripts> component.

import { ScrollRestoration } from "react-router";

export default function Root() {
  return (
    <html>
      <body>
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

Type Declaration

export interface ScrollRestorationProps {
  getKey?: GetScrollRestorationKeyFunction;
  storageKey?: string;
  nonce?: string;
}

export function ScrollRestoration({
  getKey,
  storageKey,
  nonce,
}: ScrollRestorationProps): React.ReactElement | null;

type GetScrollRestorationKeyFunction = (
  location: Location,
  matches: UIMatch[]
) => string;

Props

GetScrollRestorationKeyFunction

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 later navigations to prior paths will restore the scroll.Defaults to location.key.

<ScrollRestoration
  getKey={(location, matches) => {
    // Restore based on a unique location key (default behavior)
    return location.key;

    // Restore based on pathname
    return location.pathname;

    // Restore based on some paths, but not others
    const paths = ["/", "/chat"];
    return paths.includes(location.pathname)
      ? location.pathname
      : location.key;
  }}
/>

string

The key to use for storing scroll positions in sessionStorage. Defaults to "react-router-scroll-positions".

<ScrollRestoration storageKey="my-app-scroll" />

string

The nonce to use for the inline script tag. This is useful for Content Security Policy (CSP) compliance.

<ScrollRestoration nonce={cspNonce} />

Examples

Basic Usage

import { ScrollRestoration, Scripts } from "react-router";

export default function Root() {
  return (
    <html>
      <head>
        <title>My App</title>
      </head>
      <body>
        <Outlet />
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

Pathname-based Restoration

<ScrollRestoration
  getKey={(location) => {
    // Always restore scroll to the same position for a given pathname
    return location.pathname;
  }}
/>

Conditional Restoration

<ScrollRestoration
  getKey={(location, matches) => {
    // Don't restore scroll on the home page
    if (location.pathname === "/") {
      return location.key;
    }

    // Restore scroll for list pages but not detail pages
    const isListPage = matches.some(
      (match) => match.handle?.scrollMode === "list"
    );

    return isListPage ? location.pathname : location.key;
  }}
/>

// In route configuration
{
  path: "products",
  Component: ProductsList,
  handle: { scrollMode: "list" },
}

With CSP Nonce

export default function Root() {
  const nonce = useNonce(); // Get nonce from your app

  return (
    <html>
      <body>
        <Outlet />
        <ScrollRestoration nonce={nonce} />
        <Scripts nonce={nonce} />
      </body>
    </html>
  );
}

Preventing Scroll Reset

You can prevent scroll reset on individual navigations using the preventScrollReset prop on <Link> or <Form>:

import { Link, ScrollRestoration } from "react-router";

function App() {
  return (
    <>
      <nav>
        {/* Changing tabs shouldn't reset scroll */}
        <Link to="?tab=one" preventScrollReset>
          Tab One
        </Link>
        <Link to="?tab=two" preventScrollReset>
          Tab Two
        </Link>
      </nav>

      <ScrollRestoration />
    </>
  );
}

Behavior

Saves scroll positions to sessionStorage on navigation
Restores scroll positions on back/forward navigation
Resets scroll to top on new navigations (push)
Renders an inline <script> to prevent scroll flashing
Script runs before React hydrates to restore scroll immediately

How It Works

On mount and navigation, saves the current scroll position to sessionStorage
On back/forward navigation, restores the scroll position from sessionStorage
The inline script prevents scroll flashing by restoring scroll before React hydrates
Uses location.key by default to uniquely identify each location in the history stack

Notes

Only render one <ScrollRestoration> per app
Should be rendered before <Scripts> in the document
Works automatically with browser back/forward buttons
Respects preventScrollReset on <Link> and <Form> components
In SPA mode (no server rendering), returns null as there’s nothing to restore initially

Styling Considerations

If you’re using CSS selectors like nav :last-child, be aware that <ScrollRestoration> may render <link rel="prefetch"> tags after your navigation links. Use nav :last-of-type instead:

/* Don't use this */
nav :last-child {
  margin-right: 0;
}

/* Use this instead */
nav :last-of-type {
  margin-right: 0;
}

Components

Hooks

Routers

Route Module

Utilities

Server APIs

Vite Plugin

Config

Type Declaration

Props

Examples

Basic Usage

Pathname-based Restoration

Conditional Restoration

With CSP Nonce

Preventing Scroll Reset

Behavior

How It Works

Notes

Styling Considerations

​Type Declaration

​Props

​Examples

​Basic Usage

​Pathname-based Restoration

​Conditional Restoration

​With CSP Nonce

​Preventing Scroll Reset

​Behavior

​How It Works

​Notes

​Styling Considerations

Type Declaration

Props

Examples

Basic Usage

Pathname-based Restoration

Conditional Restoration

With CSP Nonce

Preventing Scroll Reset

Behavior

How It Works

Notes

Styling Considerations