@donis3/use-scroll-handler v1.0.1

Introduction

The scroll-handler hook is a lightweight and customizable hook that allows you to listen to scroll events and execute a callback function with detailed scroll-related data. This hook provides information about scroll direction, position, speed, and whether the user has reached the top or bottom of the scrollable container.

Installation

npm i @donis3/use-scroll-handler

Usage

Importing the hook

Import the hook at the top of your page. If you're using Next.Js 13+, you must be in a client component.

import useScrollHandler from '@donis3/use-scroll-handler';

Creating a callback

In the callback function, you will have access to many scroll related properties and you can create your logic in here.

const handleScroll = scrollData => {
  // Your callback logic here
  console.log('Scroll Data:', scrollData); // {y: 0, x: 0, directionY: null...}
};

Callback Data Structure

Inside your callback, you will be able to act upon these properties

{
  directionY: 'up' | 'down' | null,
  directionX: 'right' | 'left' | null,
  y: number,
  x: number,
  speedX: number,
  speedY: number,
  atBottom: boolean,
  atTop: boolean,
}

• directionY: Scroll direction on the Y-axis ('up', 'down', or null).
• directionX: Scroll direction on the X-axis ('right', 'left', or null).
• y: Current vertical scroll position.
• x: Current horizontal scroll position.
• speedX: Speed of horizontal scrolling. (pixels/second)
• speedY: Speed of vertical scrolling. (pixels/second)
• atBottom: Indicates whether the user has reached the bottom of the scrollable container.
• atTop: Indicates whether the user has reached the top of the scrollable container.

Listen to an element instead of the window

If you have a scrollable div with overflow-auto or overflow-scroll, you can listen to that specific element for scroll events using this hook. You must provide a ref object that points to the target element.

import useScrollHandler from '@donis3/use-scroll-handler';

function MyComponent() {
    //Create a ref
    const targetRef = useRef(null);
    //Pass your callback function and options
    useScrollHandler(handleScroll, {target: targetRef});
    //Create your callback function
    const handleScroll = (data) => {
        //Handle scroll logic
        console.log(data.speedY)
    }

    //Render component and reference your target
    return (
        ...
        <div ref={targetRef}>
            ...scrollable content
        </div>
        ...
    );
}

Full TypeScript Example (Listen to window)

Here is an example where we listen to scroll events and hide/show a navbar depending on scroll direction. When user is scrolling down, hide the navbar and show when scrolling up.

'use client'; //Required if using next.js
import useScrollHandler, { ScrollData }  from '@donis3/use-scroll-handler';

export default function Navbar() {
  const headerRef = useRef<HTMLDivElement>(null);
  useScrollHandler(scrollHandler);

  //Callback function when a scroll event occurs
  function scrollHandler(data: ScrollData) {
    //Handle scroll down event.
    if (data.directionY === 'down' && data.y > 400) {
      //Hide navbar if we are at least 400px away from the top and going down
      headerRef.current.style.transform = 'translate(0, -100px)';
    } else if (data.directionY === 'up') {
      //Show navbar when moving up
      headerRef.current.style.transform = 'translate(0, 0)';
    }
  }
  //Render navbar
  return <header ref={headerRef}>Navbar</header>;
}

License

This project is licensed under the MIT License.