use-closest-scroll
TypeScript icon, indicating that this package has built-in type declarations

1.0.0 • Public • Published

use-closest-scroll

React hook to automatically scroll to closest predefined element when the user stops scrolling.

Better demonstrated than explained: example

In short, it does not affect or restrict the user's scrolling, but when they stop scrolling, the view is snapped to one of the predefined elements.

Usage

import useClosestScroll from 'use-closest-scroll';

const App = () => {
  const element1 = useRef(null);
  const element2 = useRef(null);
  const element3 = useRef(null);

  useClosestScroll([element1, element2, element3], {
    delay: 500,
    centerOnScreen: true,
    startAfter: element1,
    stopAfter: element3
  });

  return (
    <>
      <div ref={element1}>{/* ... */}</div>
      <div ref={element2}>{/* ... */}</div>
      <div ref={element3}>{/* ... */}</div>
    </>
  }
);

The first argument is an array of refs to all the elements, which you want the view to snap to.

The second arguments are options, which are not required.

If you want to enable the module after a certain element, pass a ref to it as the startAfter option. If you want to disable the module after a certain element, pass a ref to it as the stopAfter option.

Options

option default type description
delay 500 number time (in ms) to wait after the user stops scrolling
centerOnScreen false boolean whether to scroll so the target element is in the middle of screen. when false, it goes at the top
startAfter undefined RefObject ref to the element after which you want to enable the module
stopAfter undefined RefObject ref to the element after which you want to disable the module
scroller - (scrollTo: number) => void function which does the scrolling

Custom scroller

If you don't like the default scroll behavior, you can pass a custom function to do the scrolling.

...

const customScroller = (scrollTo: number) => {
  // scroll to the target position however you like, e.g.:
  document.documentElement.scrollTo({ top: scrollTo });
}

useClosestScroll([element1, element2, element3], {
  scroller: customScroller
});

API (exports)

This module is written in TypeScript, so the types are included.

Default export

useClosestScroll: (elements: RefObject<HTMLElement>[], { startAfter, stopAfter, delay, centerOnScreen, scroller }?: Options) => () => void

Scroller

Type for a custom function to do the scrolling. Accepted as part of Options.

type Scroller = (scrollTo: number) => void;

Options

interface Options {
  delay?: number;
  centerOnScreen?: boolean;
  startAfter?: RefObject<HTMLElement>;
  stopAfter?: RefObject<HTMLElement>;
  scroller?: Scroller;
}

License

Licensed under the MIT License.

Readme

Keywords

Package Sidebar

Install

npm i use-closest-scroll

Weekly Downloads

7

Version

1.0.0

License

MIT

Unpacked Size

9.99 kB

Total Files

11

Last publish

Collaborators

  • onestopjs