react-router-scroll

React Router scroll management.

react-router-scroll is a React Router middleware that adds scroll management using scroll-behavior. By default, the middleware adds browser-style scroll behavior, but you can customize it to scroll however you want on route transitions.

This library does not currently support React Router v4, because React Router v4 has no concept of router middlewares. See ongoing discussion in #52. For an interim solution for just scrolling to top on navigation, see the React Router documentation on scroll restoration.

Usage

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

/* ... */

ReactDOM.render(
  <Router
    history={browserHistory}
    routes={routes}
    render={applyRouterMiddleware(useScroll())}
  />,
  container
);

Guide

Installation

$ npm i -S react react-dom react-router
$ npm i -S react-router-scroll

Basic usage

Apply the useScroll router middleware using applyRouterMiddleware, as in the example above.

Custom scroll behavior

You can provide a custom shouldUpdateScroll callback as an argument to useScroll. This callback is called with the previous and the current router props.

The callback can return:

a falsy value to suppress updating the scroll position
a position array of x and y, such as [0, 100], to scroll to that position
a string with the id or name of an element, to scroll to that element
a truthy value to emulate the browser default scroll behavior

useScroll((prevRouterProps, { location }) => (
  !prevRouterProps || location.pathname !== prevRouterProps.location.pathname
));

useScroll((prevRouterProps, { routes }) => {
  if (routes.some(route => route.ignoreScrollBehavior)) {
    return false;
  }

  if (routes.some(route => route.scrollToTop)) {
    return [0, 0];
  }

  return true;
});

You can customize useScroll even further by providing a configuration object with a createScrollBehavior callback that creates the scroll behavior object. This allows using a custom subclass of ScrollBehavior from scroll-behavior with custom logic. When using a configuration object, you can specify the shouldUpdateScroll callback as above under the shouldUpdateScroll key.

useScroll({
  createScrollBehavior: (config) => new MyScrollBehavior(config),
  shouldUpdateScroll,
});

Scrolling elements other than `window`

Use <ScrollContainer> in components rendered by a router with the useScroll middleware to manage the scroll behavior of elements other than window. Each <ScrollContainer> must be given a unique scrollKey, and can be given an optional shouldUpdateScroll callback that behaves as above.

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

function Page() {
  /* ... */

  return (
    <ScrollContainer
      scrollKey={scrollKey}
      shouldUpdateScroll={shouldUpdateScroll}
    >
      <MyScrollableComponent />
    </ScrollContainer>
  );
}

<ScrollContainer> does not support on-the-fly changes to scrollKey or to the DOM node for its child.

Notes

Minimizing bundle size

If you are not using <ScrollContainer>, you can reduce your bundle size by importing the useScroll module directly.

import useScroll from 'react-router-scroll/lib/useScroll';

Server rendering

Do not apply the useScroll middleware when rendering on a server. You may use <ScrollContainer> in server-rendered components; it will do nothing when rendering on a server.

taion/react-router-scroll