@lonli-lokli/scroll-restoration

React Scroll Restoration

A lightweight, framework-agnostic scroll restoration solution for React applications. This library helps preserve and restore scroll positions when navigating between pages, providing a smoother user experience.

Features

• Restore scroll positions when navigating back and forth
• No router dependencies
• Compatible with any React routing solution
• Works with nested scrollable elements
• Supports custom location key strategies
• Configurable scroll behavior
• Extensible navigation detection

Installation

npm install react-scroll-restoration
# or
yarn add react-scroll-restoration
# or
pnpm add react-scroll-restoration

Basic Usage

import { ScrollRestoration } from 'react-scroll-restoration';

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

Advanced Usage

Custom Configuration

import { ScrollRestoration } from 'react-scroll-restoration';

function App() {
  return (
    <>
      <ScrollRestoration 
        // Use only pathname for identifying routes
        getKey={(location) => location.pathname}
        // Enable smooth scrolling
        scrollBehavior="smooth"
      />
      {/* Your application content */}
    </>
  );
}

With React Router

import { ScrollRestoration } from 'react-scroll-restoration';
import { useLocation, useNavigate } from 'react-router-dom';

function App() {
  const location = useLocation();
  
  return (
    <>
      <ScrollRestoration 
        // Use React Router's location
        getCurrentLocation={() => ({
          href: window.location.href,
          pathname: location.pathname,
          search: location.search,
          hash: location.hash,
          state: location.state,
        })}
        // Listen for React Router navigation
        navigationListener={(onNavigate) => {
          const unlisten = history.listen(() => {
            onNavigate(location);
          });
          return unlisten;
        }}
      />
      {/* Your application content */}
    </>
  );
}

With Next.js

import { ScrollRestoration } from 'react-scroll-restoration';
import { useRouter } from 'next/router';

function MyApp({ Component, pageProps }) {
  const router = useRouter();
  
  return (
    <>
      <ScrollRestoration 
        getKey={(location) => location.pathname}
        navigationListener={(onNavigate) => {
          const handleRouteChange = () => {
            onNavigate({
              pathname: router.pathname,
              search: router.query ? Object.entries(router.query)
                .map(([key, value]) => `${key}=${value}`)
                .join('&') : '',
              hash: window.location.hash,
              href: window.location.href,
              state: history.state,
            });
          };
          
          router.events.on('routeChangeComplete', handleRouteChange);
          
          return () => {
            router.events.off('routeChangeComplete', handleRouteChange);
          };
        }}
      />
      <Component {...pageProps} />
    </>
  );
}

export default MyApp;

Scrollable Elements

Using data attribute (recommended)

function LongList() {
  return (
    <div 
      className="overflow-auto h-80"
      data-scroll-restoration-id="user-comments"
    >
      {/* Long list content */}
    </div>
  );
}

Using imperative handle

import { useRef, useEffect } from 'react';
import { useElementScrollRestoration } from 'react-scroll-restoration';

function LongList() {
  const containerRef = useRef<HTMLDivElement>(null);
  
  // Get stored scroll position
  const scrollPosition = useElementScrollRestoration({
    getElement: () => containerRef.current,
  });
  
  // Apply stored scroll position on mount
  useEffect(() => {
    if (containerRef.current && scrollPosition) {
      containerRef.current.scrollLeft = scrollPosition.scrollX;
      containerRef.current.scrollTop = scrollPosition.scrollY;
    }
  }, [scrollPosition]);
  
  return (
    <div 
      ref={containerRef}
      className="overflow-auto h-80"
    >
      {/* Long list content */}
    </div>
  );
}

API Reference

useScrollRestoration(options?)

The main hook for enabling scroll restoration.

Options

Option	Type	Description
getKey	(location: Location) => string	Function to generate a unique key for a location
scrollBehavior	'auto' | 'smooth'	Scroll behavior when restoring position
getCurrentLocation	() => Location	Function to get current location
navigationListener	(onNavigate: (location: Location) => void) => () => void	Function to listen for location changes

ScrollRestoration Component

A component wrapper for useScrollRestoration that returns null.

<ScrollRestoration
  getKey={(location) => location.pathname}
  scrollBehavior="smooth"
/>

useElementScrollRestoration(options)

A hook for retrieving stored scroll positions for specific elements.

Options

Option	Type	Description
id	string	ID to use with data-scroll-restoration-id attribute
getElement	() => Element | null | undefined	Function to get the element reference
getKey	(location: Location) => string	Function to generate a unique key for a location
getCurrentLocation	() => Location	Function to get current location

Browser Support

The library works in all modern browsers that support these APIs:

• sessionStorage
• window.history
• MutationObserver

TypeScript Support

This library is written in TypeScript and provides type definitions out of the box.

License

MIT