ScrollRestoration

The ScrollRestoration component persists scroll position across page refreshes using sessionStorage. It renders nothing visually but handles all scroll save/restore logic automatically.

Usage

Basic Usage

Add the component to your app root to enable scroll restoration across all pages:

import { ScrollRestoration } from "@228-co/reef/components";

function App() {
  return (
    <>
      <ScrollRestoration />
      <Router>
        {/* Your app content */}
      </Router>
    </>
  );
}

Custom Storage Key

Use different storage keys for different apps or sections to keep scroll positions separate:

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

Adjusting Wait Time

For pages with slow-loading content, increase the max wait time:

<ScrollRestoration maxWaitTime={5000} pollInterval={100} />

How It Works

The component handles scroll persistence through these mechanisms:

1. Browser Scroll Restoration

Sets history.scrollRestoration = "manual" to prevent the browser's native scroll restoration from interfering.

2. Saving Position

Saves scroll position to sessionStorage on scroll events (debounced at 100ms) and before page unload. The saved data includes the current path, so positions are only restored on the same page.

3. Restoring Position

On mount, polls until the document is tall enough to scroll to the saved position. This handles async content that may not be immediately available on page load.

Props

Name	Type	Default	Description
storageKey	string	'reef-scroll-position'	Storage key used to save scroll position in sessionStorage. Use different keys for different pages/apps.
maxWaitTime	number	2500	Maximum time in milliseconds to wait for content to load before scrolling. Useful for pages with async content.
pollInterval	number	50	Interval in milliseconds between scroll attempts while waiting for content to load.

Notes

- Uses sessionStorage, so scroll positions persist across page refreshes but clear when the browser tab is closed.

- Only restores scroll position when the saved path matches the current path.

- The component renders null and has no visual output.