# @moxy/next-scroll-behavior

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

Latest version **1.0.2** (published 2020-08-07) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install @moxy/next-scroll-behavior
pnpm add @moxy/next-scroll-behavior
yarn add @moxy/next-scroll-behavior
bun add @moxy/next-scroll-behavior
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 1.0.2 |
| Published | 2020-08-07 |
| First published | 2020-06-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 16.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 103 |
| Author | Afonso Reis |
| Maintainers | acostalima, afonsoreis05, carsy, dominguesgm, filipediasf, fsdiogo, guilhermedeandrade, hugomrdias, jdiogopeixoto, jgradim, marcooliveira, moxyhq, nlfonseca, pedromiguelss, raising, ricardo-silva91, ritazoliveira, ruimonteiro, ruipneves, satazor, threequartersjohn, vascosantos |
| Keywords | template |

## Links

- npm: https://www.npmjs.com/package/@moxy/next-scroll-behavior
- Repository: https://github.com/moxystudio/next-scroll-behavior
- Homepage: https://github.com/moxystudio/next-scroll-behavior#readme
- Issues: https://github.com/moxystudio/next-scroll-behavior/issues
- npm.io page: https://npm.io/package/@moxy/next-scroll-behavior

## Dependencies (3)

- [history](https://npm.io/package/history.md) ^3.0.0
- [prop-types](https://npm.io/package/prop-types.md) ^15.7.2
- [scroll-behavior](https://npm.io/package/scroll-behavior.md) ^0.9.11

## Recent versions

- 1.0.2 (latest) — 2020-08-07
- 1.0.1 — 2020-06-01
- 1.0.0 — 2020-06-01

## README

# next-scroll-behavior

[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Build Status][build-status-image]][build-status-url] [![Coverage Status][codecov-image]][codecov-url] [![Dependency status][david-dm-image]][david-dm-url] [![Dev Dependency status][david-dm-dev-image]][david-dm-dev-url]

[npm-url]:https://npmjs.org/package/@moxy/next-scroll-behavior
[downloads-image]:https://img.shields.io/npm/dm/@moxy/next-scroll-behavior.svg
[npm-image]:https://img.shields.io/npm/v/@moxy/next-scroll-behavior.svg
[build-status-url]:https://github.com/moxystudio/next-scroll-behavior/actions
[build-status-image]:https://img.shields.io/github/workflow/status/moxystudio/next-scroll-behavior/Node%20CI/master
[codecov-url]:https://codecov.io/gh/moxystudio/next-scroll-behavior
[codecov-image]:https://img.shields.io/codecov/c/github/moxystudio/next-scroll-behavior/master.svg
[david-dm-url]:https://david-dm.org/moxystudio/next-scroll-behavior
[david-dm-image]:https://img.shields.io/david/moxystudio/next-scroll-behavior.svg
[david-dm-dev-url]:https://david-dm.org/moxystudio/next-scroll-behavior?type=dev
[david-dm-dev-image]:https://img.shields.io/david/dev/moxystudio/next-scroll-behavior.svg

`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

```sh
$ 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](https://www.npmjs.com/package/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.

```js
// ...

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 |

```js
const scrollBehaviorOptions = {
    disableNextLinkScroll: false;
}

const scrollBehavior = getScrollBehavior(scrollBehaviorOptions);
```

## Tests

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

## Demo

A demo [Nextjs](https://nextjs.org/) project is available in the [`/demo`](./demo) folder so you can try out this component.

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

```sh
$ 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*

```sh
$ npm run dev
```

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

```sh
$ npm i
$ npm run dev
```

## License

Released under the [MIT License](https://www.opensource.org/licenses/mit-license.php).

---
_Source: https://npm.io/package/@moxy/next-scroll-behavior · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._