Note: this fork just updates peer dependencies so this library works with
next^13
andreact^18
. Existing tests pass with those versions.
Take control of when scroll is updated and restored in your Next.js projects.
$ npm install @moxy/next-router-scroll
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.
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.
@moxy/next-router-scroll
makes it easy to update the window scroll position just like a browser would, but programmatically.
This package is built on top of scroll-behavior and it's meant to be used in Next.js applications. It actively listens to Next.js router events, writing the scroll values associated with the current location
in the Session Storage
and reading these values whenever updateScroll()
is called.
First install the provider in your app:
// pages/_app.js
import { RouterScrollProvider } from '@moxy/next-router-scroll';
const App = ({ Component, pageProps }) => (
<RouterScrollProvider>
<Component { ...pageProps } />
</RouterScrollProvider>
);
export default App;
Then use the hook or HOC to update the scroll whenever you see fit.
// pages/index.js
import { useRouterScroll } from '@moxy/next-router-scroll';
const Home = () => {
const { updateScroll } = useRouterScroll();
useEffect(() => {
updateScroll();
}, []);
};
export default Home;
⚠️ By default,<RouterScrollProvider />
monkey patches Next.js<Link />
component, changing thescroll
prop default value tofalse
. You can disable this behavior by setting thedisableNextLinkScroll
prop tofalse
.
A provider that should be used in your app component.
Type: function
A function to determine if scroll should be updated or not.
// pages/_app.js
import { RouterScrollProvider } from '@moxy/next-router-scroll';
const App = ({ Component, pageProps }) => {
const shouldUpdateScroll = useMemo((prevContext, context) => {
// Both arguments have the following shape:
// {
// location,
// router: { pathname, asPath, query }
// }
}, []);
return (
<RouterScrollProvider shouldUpdateScroll={ shouldUpdateScroll }>
<Component { ...pageProps } />
</RouterScrollProvider>
);
};
export default App;
Check custom scroll behavior for more information.
⚠️ Please note thatprevContext
might be null on the first run.
Type: boolean
Default: true
True to set Next.js Link default scroll
property to false
, false otherwise. Since the goal of this package is to manually control the scroll, you don't want Next.js default behavior of scrolling to top when clicking links.
Type: ReactNode
Any React node to render.
A hook that returns an object with the following shape:
{
updateScroll(prevContext?, context?),
registerElement(key, element, shouldUpdateScroll?, context?),
unregisterElement(key)
}
Call updateScroll
function whenever you want to update the scroll. You may optionally pass prevContext
and context
objects which will be available inside shouldUpdateScroll
.
Please note that prevContext
and context
have default values and any values you pass will be mixed with the default ones.
Use With Async Rendering:
If you're asyncronously loading DOM elements and need to wait for an element you can utilize React's approach for measuring DOM nodes. Here is an example of what that could look like:
const MyComponent = () => {
const { updateScroll } = useRouterScroll();
const divRef = useCallback((node) => {
if (node) {
updateScroll();
}
}, [updateScroll]);
return someCondition ? <div ref={ divRef }>hi</div> : null;
};
Call registerElement
method to register an element other than window to have managed scroll behavior. Each of these elements needs to be given a unique key at registration time, and can be given an optional shouldUpdateScroll
callback that behaves as above. This method can optionally be called with the current context if applicable, to set up the element's initial scroll position.
Call unregisterElement
to unregister a previously registered element, identified by key
.
A HOC that injects a routerScroll
prop, with the same value as the hook variant.
import { withRouterScroll } from '@moxy/next-router-scroll';
const MyComponent = ({ routerScroll }) => {
// ...
};
export default withRouterScroll(MyComponent);
$ npm test
$ npm test -- --watch # during development
A demo project is available in the /demo
folder so you can try out this component.
First, build the next-router-scroll
project with:
$ npm run build
Note: Every time 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
Released under the MIT License.