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
xandy, such as[0, 100], to scroll to that position - a string with the
idornameof 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.