scrollen

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.