Gatsby React Router Scroll Management

Common errors

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

  cause 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"

  cause 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.

  cause 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>);`

Warnings

• breaking This 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.
• breaking Gatsby, 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.
• gotcha Scroll 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.
• gotcha Enabling 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.

Install

• npm install gatsby-react-router-scroll npm
• yarn add gatsby-react-router-scroll yarn
• pnpm add gatsby-react-router-scroll pnpm

Imports

• ScrollManager
  wrong:

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

  correct:

  import { ScrollManager } from '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.

Quickstart

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';