vdmrgv / react-scroll-percentage-hook

💯 A React hook to monitor component scroll percentage.

react-scroll-percentage-hook

A React hook that reports the element's current scroll percentage. Can be used for both scroll axes.
Check out the demo for some examples.

Features

• 🚀 Fast - Built with hooks and functional components only.
• 📏 No need to specify sizes - No need to pass the dimensions of the component, scrollbar or element
• 👫 Cross-browser - Works out-of-the-box for most browsers, regardless of version.
• 📲 Mobile-friendly - Supports mobile devices and touch screens.
• 🛠 Written in TypeScript - It'll fit right into your existing TypeScript project
• 💥 Lightweight - Around ~400B

Install

  # with npm
  npm install --save react-scroll-percentage-hook
  # with yarn
  yarn add react-scroll-percentage-hook

Usage

import useScrollPercentage from 'react-scroll-percentage-hook';

const Component = () => {
  // TypeScript example:
  // const { ref, percentage } = useScrollPercentage<HTMLDivElement>(...props);
  const { ref, percentage } = useScrollPercentage();

  return (
    <>
      <p>{`vertical: ${percentage.vertical} horizontal: ${percentage.horizontal}`}</p>
      <div ref={ref}>
        {items.map((item, index) => (
          <div key={index}>{item}</div>
        ))}
      </div>
    </>
  );
};

API

Name	Description	Type	Required	Default Value
windowScroll	If enabled uses window scroll	boolean	❌	false
onProgress	Callback called when scrolling ({ vertical, horizontal }) => void	function	❌	undefined
timeout	Timeout for scroll handler in ms	number	❌	10

Supported Browsers

react-scroll-percentage-hook does not have a specific API to work with, so it supports all browsers from early versions and will support all evergreen browsers and the latest mobile browsers for iOS and Android. IE 9+ is also supported.

If you find a browser-specific problem, please report it.

Contributing

Please read through our contributing guidelines. Included are directions for opening issues, coding standards, and notes on development.

License

Code released under the MIT License.