A robust scroll restoration library for Next.js App Router that supports custom scrollable elements.
Next Scroll Restoration solves the problem of preserving scroll positions for custom scrollable elements in Next.js applications, which is not natively supported by Next.js's built-in scroll restoration feature. Check out our demo to see it in action.
- 🔄 Preserves scroll position for custom scrollable elements
- 🚀 Works seamlessly with Next.js App Router and its built-in scroll restoration
- 🖱️ Supports multiple scrollable areas within a single page
- 🔧 Fine-grained control over scroll behavior via URL parameters
- 🏎️ Performance-optimized with batched updates to sessionStorage
- 📦 Minimal setup required
- 🧠 Handles edge cases like same-page navigation, initial page load, hard reload, and more
npm install next-scroll-restorationimport React from 'react'
import { ScrollRestoration } from 'next-scroll-restoration'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html>
<body>
{children}
<ScrollRestoration />
</body>
</html>
)
}- Add the
ScrollRestorationcomponent to your root layout. - Mark scrollable elements with the
data-scroll-restoration-idattribute:
<div
data-scroll-restoration-id="container"
style={{
height: '100dvh',
overflowY: 'scroll',
}}
>
Your scrollable content
</div>- Use URL parameters to control scroll behavior:
?scroll=falseor?scroll=0: Disable scroll restoration?scroll=trueor?scroll=1: Force scroll to top (useful for same-page navigation)
- Designed to work alongside Next.js's built-in scroll restoration feature
- Handles scroll restoration for elements explicitly marked with
data-scroll-restoration-idattribute - Uses
sessionStorageto persist scroll positions across page reloads - Utilizes React hooks and Next.js routing for efficient state management
- Handles various navigation scenarios including history push/forward/reload
- Handles Next.js App Router features like async Components, nested Suspense boundaries, and SSG correctly
- Implements a pre-hydration script to eliminate flickering (experimental: optional)
-
Same-page navigation: To ensure scroll-to-top behavior, use:
<Link href="/same-page?scroll=true">Link</Link>
-
Page navigation with scroll: false: When using Next.js scroll options, also specify in the URL:
<Link href="/another-page?scroll=false" scroll={false}> Link </Link>
router.push('/another-page?scroll=false', { scroll: false })
-
Search query cleanup: The
scrollsearch query is automatically removed after scroll restoration.
Experimental (React 19+ Only)
For cases where you notice flickering on initial page load or first navigation,
you can optionally use the ScrollRestorationBeforeHydration component:
import React from 'react'
import {
ScrollRestoration,
experimental_ScrollRestorationBeforeHydration as ScrollRestorationBeforeHydration,
} from 'next-scroll-restoration'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html>
<body>
{children}
<ScrollRestoration>
<ScrollRestorationBeforeHydration />
</ScrollRestoration>
</body>
</html>
)
}This component injects a script that runs before React hydration, restoring scroll position immediately after content becomes readable.
Compatible with all modern browsers that support sessionStorage and
ResizeObserver.