Registry / web-framework / gatsby-react-router-scroll

gatsby-react-router-scroll

library6.16.0jsnpmunverified

gatsby-react-router-scroll is a Gatsby plugin designed to manage scroll behavior across page transitions, specifically within Gatsby applications that leverage `@reach/router`. It is a direct fork of `react-router-scroll`, which itself was an adaptation for React Router v4 from an earlier version, and has been further modified to be compatible with Gatsby's internal `@reach/router` usage. The current stable version is 6.16.0. As a utility tightly integrated with Gatsby, its release cadence generally aligns with Gatsby's main releases, typically seeing monthly minor updates and frequent patch releases. Its primary differentiation is its tight integration and optimization for the Gatsby ecosystem and its `@reach/router` dependency, providing a seamless scroll restoration experience without requiring extensive manual intervention, which is crucial for modern single-page application (SPA) navigation patterns.

web-framework http-networking serialization

npm install gatsby-react-router-scroll

github ↗package ↗

INSTALL

IMPORT

SIG · GATSBY-REACT-ROUTE

gatsby-react-router-scroll

web-frameworkjavascriptv6.16.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ScrollManager

✓ import { ScrollManager } from 'gatsby-react-router-scroll';

✗ const ScrollManager = require('gatsby-react-router-scroll');

The primary component for wrapping Gatsby page elements to enable scroll management. Use named import for ESM environments.

wrapPageElement

✓ export const wrapPageElement = ({ element, props }) => { /* ... */ };

While not directly imported from `gatsby-react-router-scroll`, `wrapPageElement` is the standard Gatsby Browser API hook used to integrate `ScrollManager` into your application.

Demonstrates how to integrate `gatsby-react-router-scroll` into a Gatsby project using the `wrapPageElement` browser API to manage scroll restoration across page transitions.

import React from 'react'; import { ScrollManager } from 'gatsby-react-router-scroll'; // In your gatsby-browser.js file export const wrapPageElement = ({ element, props }) => { const { location, action } = props; return ( <ScrollManager location={location} action={action} autoElementScroll={true} // Automatically scroll to the top of the page on route change timeout={100} // Optional: Adjust the timeout for scroll restoration (ms) > {element} </ScrollManager> ); }; // Optional: For server-side rendering (SSR), you can also export from gatsby-ssr.js // export { wrapPageElement } from './gatsby-browser';

Debug

Known issues

breakingThis package underwent significant internal changes to align with Gatsby's adoption of `@reach/router`. Direct usage with `react-router-dom` (versions v5, v6, or earlier) will not function correctly due to fundamental API and architectural differences in routing libraries.

fix

Ensure your project uses Gatsby's `@gatsbyjs/reach-router` internally. This plugin is not intended for use with standalone `react-router-dom` setups. Upgrading Gatsby to a compatible version (v4+) will generally provide the correct `@reach/router` environment.

affects: <6.0.0

breakingGatsby, and by extension this plugin, has specific Node.js version requirements. Using unsupported Node.js versions (e.g., <18.0.0 or >=26.0.0) can lead to installation failures, build errors, or unexpected runtime behavior.

fix

Ensure your Node.js environment is within the supported range for Gatsby v5 (currently `>=18.0.0 <26.0.0`). Utilize tools like `nvm` or `volta` to manage and switch between Node.js versions effectively.

affects: *

gotchaScroll restoration provided by this plugin might not work optimally or consistently for pages that dynamically load content after the initial render, or for components that manually manipulate scroll position. The scroll point is determined early in the navigation lifecycle.

fix

For highly dynamic content, consider manually triggering scroll updates (e.g., using `window.scrollTo(x, y)` or a custom `useEffect` hook) after asynchronous data or components have rendered. Adjusting the `timeout` prop on `ScrollManager` may help in some cases but is not a universal solution.

affects: >=6.0.0

gotchaEnabling multiple scroll management solutions simultaneously (e.g., another Gatsby plugin for scroll, custom `useEffect` hooks, or conflicting browser settings) can lead to unpredictable, 'jumpy,' or incorrect scroll positions.

fix

Review your `gatsby-browser.js` and other project dependencies to ensure only one scroll restoration mechanism is active. This plugin is designed to be the primary scroll manager for Gatsby's internal routing.

affects: >=6.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'location') or (reading 'action')

The `ScrollManager` component is not receiving the required `location` or `action` props, typically when used outside of Gatsby's `wrapPageElement` API or when the props are not correctly spread.

fix

Ensure you are passing `location={props.location}` and `action={props.action}` directly to the `ScrollManager` within your `gatsby-browser.js` `wrapPageElement` export.

error glob@11.0.3: The engine "node" is incompatible with this module. Expected version "20 || >=22". Got "18.6.0"

This error, often seen during `npm install` or `yarn install`, indicates a mismatch between your Node.js version and Gatsby's (or its dependencies') expected Node.js version range.

fix

Upgrade your Node.js version to one compatible with Gatsby v5 (e.g., Node.js 20 or 22). Use `nvm install 20 && nvm use 20` or similar version management commands.

Component(...): Nothing was returned from render. This usually means a return statement is missing or an undefined is unexpectedly returned.

This React error can occur if the `ScrollManager` component or its parent `wrapPageElement` function does not explicitly return JSX, leading to an undefined return value for the component.

fix

Verify that your `wrapPageElement` function in `gatsby-browser.js` always returns the `ScrollManager` component with `element` as its child, like `return (<ScrollManager>{element}</ScrollManager>);`

Upgrade

Version history

6.16.0latest on npm

Audit

Dependencies

@gatsbyjs/reach-routerrequiredRequired for Gatsby's internal routing mechanism that this plugin integrates with.

reactrequiredCore React dependency for rendering components.

react-domrequiredCore React DOM dependency for rendering components to the DOM.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/gatsbyjs/gatsby ↗

packagehttps://www.npmjs.com/package/gatsby-react-router-scroll ↗