next-scroll-behavior

next-scroll-behavior provides a built in custom scroll behavior that aims to make it easy to restore the user scroll position based on location history.

Installation

$ npm install @moxy/next-scroll-behavior

This library is written in modern JavaScript and is published in both CommonJS and ES module transpiled variants. If you target older browsers please make sure to transpile accordingly.

Motivation

There are some cases where you need to take control on how your application scroll is handled; namely, you may want to restore scroll when user is navigating within your application pages, but you need to do extra work before or after the page has changed, either by using some sort of page transition or any other feature.

next-scroll-behavior provides a built-in custom scroll behavior that aims to make it easy to restore the user scroll position based on location history.

This package is built on top of scroll-behavior and it's meant to be used in Nextjs applications.

Usage

You can simply import the package and update the scroll whenever your need.

Router won't be accessible while it's not initialized, so make sure to initialize getScrollBehavior() in componentDidMount or in the equivalent useEffect hook like the example below.

// ...

import getScrollBehavior from '@moxy/next-scroll-behavior';

// ...

useEffect(() => {
    scrollBehaviorRef.current = getScrollBehavior();

    return () => {
        scrollBehaviorRef.current.stop();
    };
}, []);

// ...

const updateScroll = useCallback(() => scrollBehaviorRef.current.updateScroll(), []);

⚠️ This package monkey patches Next.js <Link /> component, changing the scroll prop default value to false. You can disable this behavior by passing disableNextLinkScroll as true in the option argument when calling getScrollBehavior().

Bear in mind that the package also sets history.scrollRestoration to manual.

How it works

This package works by actively listening to Nextjs router events on routeChangeStart, writing the scroll values associated with the current location in the Session Storage and reading these values whenever updateScroll is called.

API

The function accepts an options object argument.

Option Key	Default	Description
disableNextLinkScroll	true	Enables or disables changing the default scroll prop of Next.js <Link /> component

const scrollBehaviorOptions = {
    disableNextLinkScroll: false;
}

const scrollBehavior = getScrollBehavior(scrollBehaviorOptions);

Tests

$ npm test
$ npm test -- --watch # during development

Demo

A demo Nextjs project is available in the /demo folder so you can try out this component.

First, build the next-scroll-behavior project with:

$ npm run build

Note: Everytime a change is made to the package a rebuild is required to reflect those changes on the demo. While developing, it may be a good idea to run the dev script, so you won't need to manually run the build after every change

$ npm run dev

To run the demo, do the following inside the demo's folder:

$ npm i
$ npm run dev

License

Released under the MIT License.