Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/taion/react-router-scroll

React Router scroll management
https://github.com/taion/react-router-scroll

Last synced: 7 days ago
JSON representation

React Router scroll management

Awesome Lists containing this project

README 

        
# react-router-scroll [![Travis][build-badge]][build] [![npm][npm-badge]][npm]



[React Router](https://github.com/reactjs/react-router) scroll management.



react-router-scroll is a React Router middleware that adds scroll management using [scroll-behavior](https://github.com/taion/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](https://github.com/taion/react-router-scroll/issues/52). For an interim solution for just scrolling to top on navigation, see the React Router [documentation on scroll restoration](https://reacttraining.com/react-router/web/guides/scroll-restoration).**



## Usage



```js

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

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



/* ... */



ReactDOM.render(

  ,

  container

);

```



## Guide



### Installation



```shell

$ 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



```js

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.



```js

useScroll({

  createScrollBehavior: (config) => new MyScrollBehavior(config),

  shouldUpdateScroll,

});

```



### Scrolling elements other than `window`



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



```js

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



function Page() {

  /* ... */



  return (

    

      

    

  );

}

```



`` 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 ``, you can reduce your bundle size by importing the `useScroll` module directly.



```js

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

```



#### Server rendering



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



[build-badge]: https://img.shields.io/travis/taion/react-router-scroll/master.svg

[build]: https://travis-ci.org/taion/react-router-scroll



[npm-badge]: https://img.shields.io/npm/v/react-router-scroll.svg

[npm]: https://www.npmjs.org/package/react-router-scroll