react-router-scroll
v0.4.4
Published
React Router scroll management
Downloads
91,099
Readme
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
andy
, such as[0, 100]
, to scroll to that position - a string with the
id
orname
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.