react-scroll-manager
TypeScript icon, indicating that this package has built-in type declarations

1.0.3 • Public • Published

react-scroll-manager

Build Status npm version

Overview

In a single page application (SPA), the application manipulates the browser history and DOM to simulate navigation. Because navigation is simulated and rendering is dynamic, the usual browser behavior of restoring scroll position when navigating back and forth through the history is not generally functional. While some browsers (particularly Chrome) attempt to support automatic scroll restoration in response to history navigation and asynchronous page rendering, this support is still incomplete and inconsistent. Similarly, SPA router libraries provide varying but incomplete levels of scroll restoration. For example, the current version of React Router does not provide scroll management, and older versions did not provide support for all cases.

This library attempts to provide this missing functionality to React applications in a flexible and mostly router-agnostic way. It supports saving per-location window and element scroll positions to session storage and automatically restoring them during navigation. It also provides support for the related problem of navigating to hash links that reference dynamically rendered elements.

Requirements

This library has the following requirements:

The following features of newer browsers are supported with fallbacks for older browsers:

Installation

npm install react-scroll-manager

Example

The following example demonstrates usage of this library with React Router v4. It includes scroll restoration for both the main content window and a fixed navigation panel.

import React from 'react';
import { Router } from 'react-router-dom';
import { ScrollManager, WindowScroller, ElementScroller } from 'react-scroll-manager';
import { createBrowserHistory as createHistory } from 'history';
 
class App extends React.Component {
  constructor() {
    super();
    this.history = createHistory();
  }
  render() {
    return (
      <ScrollManager history={this.history}>
        <Router history={this.history}>
          <WindowScroller>
            <ElementScroller scrollKey="nav">
              <div className="nav">
                ...
              </div>
            </ElementScroller>
            <div className="content">
              ...
            </div>
          </WindowScroller>
        </Router>
      </ScrollManager>
    );
  }
}

API

ScrollManager

The ScrollManager component goes outside of your router component. It enables manual scroll restoration, reads and writes scroll positions from/to session storage, saves positions before navigation events, handles scrolling of nested components like WindowScroller and ElementScroller, and performs delayed scrolling to hash links anywhere within the document. It has the following properties:

Name Type Required Description
history object yes A history object, as returned by createBrowserHistory or createMemoryHistory.
sessionKey string no The key under which session state is stored. Defaults to ScrollManager.
timeout number no The maximum number of milliseconds to wait for rendering to complete. Defaults to 3000.

WindowScroller

The WindowScroller component goes immediately inside your router component. It handles scrolling the window position after navigation. If your window position never changes (e.g. your layout is fixed and all scrolling occurs within elements), it need not be used. It has no properties, but must be nested within a ScrollManager.

ElementScroller

The ElementScroller component goes immediately outside of a scrollable component (e.g. with overflow: auto style) for which you would like to save and restore the scroll position. It must be nested within a ScrollManager and has the following required property:

Name Type Required Description
scrollKey string yes The key within the session state under which the element scroll position is stored.

Tips

Use router link elements for hash links within a page

Always be sure to use your router library's link component rather than <a> tags when navigating to hash links. While a link like <a href="#id"> will navigate to the given element on the current page, it bypasses the usual call to history.pushState, which assigns a unique key to the history location. Without a location key, the library has no way to associate the position with the location, and scroll restoration won't work for those locations.

  <Link to="#id">...</Link> <!-- right way -->
  <a href="#id">...</a>     <!-- wrong way -->

Acknowledgments

License

react-scroll-manager is available under the ISC license.

Package Sidebar

Install

npm i react-scroll-manager

Weekly Downloads

374

Version

1.0.3

License

ISC

Unpacked Size

25.2 kB

Total Files

9

Last publish

Collaborators

  • trevorr