React Router Scroll Management

Common errors

• TypeError: (0, _reactRouterScroll.useScroll) is not a function

  cause Attempting to import `useScroll` as a default export after v0.3.0, or using CommonJS `require` incorrectly.
  fix Update the import statement to use named import: `import { useScroll } from 'react-router-scroll';`

• TypeError: _reactRouter.Router.applyRouterMiddleware is not a function

  cause This error occurs when trying to use `applyRouterMiddleware` with React Router v4 or newer, which has removed this API.
  fix `react-router-scroll` is incompatible with React Router v4+. Downgrade React Router to v2 or v3, or migrate your application's scroll management to a solution compatible with modern React Router versions.

• Invariant Violation: Module history does not have a module named default

  cause `history` version incompatibility with `react-router-scroll` or `react-router`, particularly after `react-router-scroll` v0.4.0 made `history` a peer dependency.
  fix Ensure your project's `history` dependency (`npm list history`) matches the `^2.0.0 || ^3.0.0` requirement and is consistent with your installed `react-router` version (v2.x or v3.x).

Warnings

• breaking The `history` package became a peer dependency in v0.4.0. Projects must explicitly install a compatible `history` version (`^2.0.0 || ^3.0.0`) that aligns with their React Router v2/v3 installation.
  Fix: Ensure `history` is installed as a dependency (`npm install history@^2.0.0 || ^3.0.0`) and that its version is compatible with your `react-router` version.
• breaking In v0.3.0, `useScroll` changed from being a default export to a named export. Incorrect import statements will lead to runtime errors.
  Fix: Update your import statements from `import useScroll from 'react-router-scroll';` to `import { useScroll } from 'react-router-scroll';`.
• gotcha This library is NOT compatible with React Router v4, v5, or v6. React Router v4 removed the router middleware concept that `react-router-scroll` relies on. Attempting to use it with newer React Router versions will result in errors.
  Fix: For React Router v4+, consult the React Router documentation for scroll restoration or use alternative community packages designed for newer React Router APIs (e.g., `react-router-dom`'s built-in scroll restoration).
• gotcha When performing server-side rendering (SSR), the `useScroll` middleware should not be applied to avoid issues related to DOM manipulation in a non-browser environment.
  Fix: Conditionally apply `useScroll` only in client-side rendering environments (e.g., `typeof window !== 'undefined'`). `<ScrollContainer>` components will gracefully do nothing on the server.
• gotcha The `<ScrollContainer>` component does not support dynamic changes to its `scrollKey` prop or to the underlying DOM node of its child. Changing these properties after initial render may lead to unexpected scroll behavior.
  Fix: Ensure `scrollKey` remains static for the lifetime of a `<ScrollContainer>` instance. If a different key or child DOM node is needed, remount the `<ScrollContainer>` component entirely.

Install

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

Imports

• useScroll
  wrong:

  import useScroll from 'react-router-scroll';

  correct:

  import { useScroll } from 'react-router-scroll';

  Changed from a default export to a named export in v0.3.0. Prior to v0.3.0, it was a default export. For bundle size optimization, consider 'import useScroll from 'react-router-scroll/lib/useScroll';'
• ScrollContainer
  wrong:

  const ScrollContainer = require('react-router-scroll').ScrollContainer;

  correct:

  import { ScrollContainer } from 'react-router-scroll';

  Used for managing scroll behavior of specific elements within a component, not the entire window. Only functions with 'useScroll' middleware applied.
• applyRouterMiddleware

  import { applyRouterMiddleware } from 'react-router';

  This symbol is imported from 'react-router' (v2/v3) itself, not 'react-router-scroll', but is essential for applying 'useScroll'.

Quickstart

This example demonstrates basic setup for `react-router-scroll` with React Router v2/v3, applying `useScroll` as a router middleware to manage default browser-style scroll behavior on route transitions.

import React from 'react';
import ReactDOM from 'react-dom';
import { applyRouterMiddleware, browserHistory, Router } from 'react-router';
import { useScroll } from 'react-router-scroll';

// Define your routes (example)
const routes = {
  path: '/',
  component: ({ children }) => (
    <div>
      <h1>Welcome</h1>
      {children}
    </div>
  ),
  indexRoute: { component: () => <p>Home Page Content</p> },
  childRoutes: [
    { path: 'about', component: () => <p>About Us Content</p> },
    { path: 'contact', component: () => <p>Contact Us Content</p> }
  ]
};

ReactDOM.render(
  <Router
    history={browserHistory}
    routes={routes}
    render={applyRouterMiddleware(useScroll())}
  />,
  document.getElementById('root')
);