Scrollen NPM | npm.io

Scrollen

A performant utility scroll hook for React.

Install

npm install scrollen

Getting Started

To start using the scrollen you need import and call the useScroller hook

import { useScroller } from 'scrollen'

const scroller = useScroller()

And that's it! By default the hook will listen to scroll on document.

If you want to use a different scroll container, you can use the setScrollerElement function

import { useScroller } from 'scrollen'

const scroller = useScroller()

<div ref={scroller.setScrollerElement}>
  ...
</div>

Example

See this small example of how you can use the hook.

Documentation

First of all, a huge thanks to @diegohaz as this library uses the Ariakit Component Stores API, so refer to the Ariakit Component Stores Guide to learn the core of the hook.

Props

Prop	Description
`initialScrollTop`	The initial `scrollTop` value to the scroller element.
`initialScrollLeft`	The initial `scrollLeft` value to the scroller element.
`startScrollAt`	Where the scroll should start. You can pass `bottom \\| right`.

State

State	Description
`element`	The scroller element.
`scrollTop`	The `scrollTop` value for the scroller element.
`scrollLeft`	The `scrollLeft` value for the scroller element.
`scrollWidth`	The `scrollWidth` value for the scroller element.
`scrollHeight`	The `scrollHeight` value for the scroller element.
`scrollY`	The progress of the vertical scroll. (between 0 and 1)
`scrollX`	The progress of the horizontal scroll. (between 0 and 1)
`scrollLengthY`	The length of the vertical scroll.
`scrollLengthX`	The length of the horizontal scroll.
`scrollDirectionY`	The direction of the vertical scroll. (`static \\| up \\| down`)
`scrollDirectionX`	The direction of the horizontal scroll. (`static \\| left \\| right`)
`isAtTop`	A boolean to check if the scroll reached the top.
`isAtBottom`	A boolean to check if the scroll reached the bottom.
`isAtLeft`	A boolean to check if the scroll reached the left.
`isAtRight`	A boolean to check if the scroll reached the right.

Functions

Function	Description
`setScrollerElement`	Function to set the scroller element.
`scrollToTop`	Function to scroll programatically to top.
`scrollToLeft`	Function to scroll programatically to left.
`scrollToBottom`	Function to scroll programatically to bottom.
`scrollToRight`	Function to scroll programtically to right.
`useOnScrollTop`	A custom hook to register a callback that is called when the scroll reached the top.
`useOnScrollBottom`	A custom hook to register a callback that is called when the scroll reached the bottom.

Acknowledgements

Ariakit - Thanks to @diegohaz for the Component Stores API that made it possible to create a performant hook.
react-virtuoso - Where did I get ideas for utilities.

react scroll hook

@ariakit/core @ariakit/react-core @changesets/cli

@everything-registry/sub-chunk-2721

0.0.2

2 years ago

0.0.1

2 years ago