Skip to content

A simple, performant, and cross-browser hook for detecting scroll direction in your next react app.

License

Notifications You must be signed in to change notification settings

AndrzejSala/use-scroll-direction

Repository files navigation

use-scroll-direction

Latest Stable Version CI Status Codecov Gzipped size License

A simple, performant, and cross-browser hook for detecting scroll direction in your next react app.

Key Features

  • Performant 🔥
    Do what is only needed. In a good way.
    Use passive listener and throttling to make it invesible for your device.

  • Versatile 💪🏼
    Handle both X & Y axis, on browser window or custom element (ref). Need more quick/lazy response? Play with wait option.

  • Microlight 🪶
    It's lighter than the air, only ~1.6kB.

  • Cross-everything 🖥️
    The same behavior on all kind of browsers and devices. No excuces (even on Iphone Safari).

  • Great support 👨🏻
    Stuck with implementation or has interesting use case and need something more? Create an issue and share your voice.

Installation

npm i use-scroll-direction

Usage

The hook returns the object with the actual scroll direction which could be one of three states: 'NONE', 'DOWN', 'UP', 'LEFT', 'RIGHT' and useful booleans.

Use on window object

import {useScrollDirection} from "use-scroll-direction";

export const WindowExample = () => {
    const {
        scrollDirection,
        isScrolling,
        isScrollingUp,
        isScrollingDown,
        isScrollingLeft,
        isScrollingRight
    } = useScrollDirection();

    useEffect(() => {
        console.log(scrollDirection)
    }, [scrollDirection]);

    return (
      <div>{...}</div>
    )
};

Use on the specific element

import {useScrollDirection} from "use-scroll-direction";

export const ComponentRefExample = () => {
    const elementRef = useRef(null);
    const {scrollDirection} = useScrollDirection({ref: elementRef});

    useEffect(() => {
        console.log(scrollDirection)
    }, [scrollDirection]);

    return (
        //The content needs to overflow a container
        <div ref={elementRef} style={{height: '100vh', overflowY: 'scroll'}} >
            <div>{...}</div>
        </div>
    )
};

Available options

Name Type Description
wait ?number Time in ms for throttling of scroll handler (default: 50)
timeToReset ?number Time in ms after last scroll event to reset the state (default: 150)
ref ?HTMLElement When passed, the listener will be attached to element instead of window object