{"id":10929,"library":"gatsby-react-router-scroll","title":"Gatsby React Router Scroll Management","description":"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.","status":"active","version":"6.16.0","language":"javascript","source_language":"en","source_url":"https://github.com/gatsbyjs/gatsby","tags":["javascript","gatsby"],"install":[{"cmd":"npm install gatsby-react-router-scroll","lang":"bash","label":"npm"},{"cmd":"yarn add gatsby-react-router-scroll","lang":"bash","label":"yarn"},{"cmd":"pnpm add gatsby-react-router-scroll","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Gatsby's internal routing mechanism that this plugin integrates with.","package":"@gatsbyjs/reach-router","optional":false},{"reason":"Core React dependency for rendering components.","package":"react","optional":false},{"reason":"Core React DOM dependency for rendering components to the DOM.","package":"react-dom","optional":false}],"imports":[{"note":"The primary component for wrapping Gatsby page elements to enable scroll management. Use named import for ESM environments.","wrong":"const ScrollManager = require('gatsby-react-router-scroll');","symbol":"ScrollManager","correct":"import { ScrollManager } from 'gatsby-react-router-scroll';"},{"note":"While not directly imported from `gatsby-react-router-scroll`, `wrapPageElement` is the standard Gatsby Browser API hook used to integrate `ScrollManager` into your application.","symbol":"wrapPageElement","correct":"export const wrapPageElement = ({ element, props }) => { /* ... */ };"}],"quickstart":{"code":"import React from 'react';\nimport { ScrollManager } from 'gatsby-react-router-scroll';\n\n// In your gatsby-browser.js file\nexport const wrapPageElement = ({ element, props }) => {\n  const { location, action } = props;\n\n  return (\n    <ScrollManager\n      location={location}\n      action={action}\n      autoElementScroll={true} // Automatically scroll to the top of the page on route change\n      timeout={100} // Optional: Adjust the timeout for scroll restoration (ms)\n    >\n      {element}\n    </ScrollManager>\n  );\n};\n\n// Optional: For server-side rendering (SSR), you can also export from gatsby-ssr.js\n// export { wrapPageElement } from './gatsby-browser';\n","lang":"typescript","description":"Demonstrates how to integrate `gatsby-react-router-scroll` into a Gatsby project using the `wrapPageElement` browser API to manage scroll restoration across page transitions."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<6.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"*"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=6.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=6.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are passing `location={props.location}` and `action={props.action}` directly to the `ScrollManager` within your `gatsby-browser.js` `wrapPageElement` export.","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.","error":"TypeError: Cannot read properties of undefined (reading 'location') or (reading 'action')"},{"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.","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.","error":"error glob@11.0.3: The engine \"node\" is incompatible with this module. Expected version \"20 || >=22\". Got \"18.6.0\""},{"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>);`","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.","error":"Component(...): Nothing was returned from render. This usually means a return statement is missing or an undefined is unexpectedly returned."}],"ecosystem":"npm"}