@ryfylke-react/scroll-handler

Scroll Handler

Create scroll effects with ease and performance in mind

Install

npm i @ryfylke-react/scroll-handler

You can also alternatively copy/paste the source directly from here.

Use

Creating a new scroll handler

import { ScrollHandler } from "@ryfylke-react/scroll-handler";

const scrollHandler = new ScrollHandler({
  target: document.querySelector("#app")!, // default: `document.body`
})
  .onScroll((event, { disable }) => {
    // Do something when scroll event is triggered
  })
  .enable();

You can call the disable util to disable the scroll handler.

Adding conditional effects and breakpoints

scrollHandler
  .between(0, 500, (event, { getPercent }) => {
    // Do something when scroll position is between 0 and 500
    const percent = getPercent();
  })
  .onceOver(500, () => {
    // Called once whenever scroll position goes from less than 500 to more than 500
  });

You can also pass elements as arguments to between, onceOver and onceUnder:

const element = document.querySelector("#element")!;
scrollHandler
  .between(0, element, () => {
    // ...
  })
  .onceOver(element, () => {
    // ...
  });

This essentially uses the elements getBoundingClientRect().top to determine the value. This value is cached, and uses a MutationObserver and debounced resize-listener to do it's best to update the value whenever the element could have changed position.

If you know that the element will not change position, you could just pass the value.

const elTop = document
  .querySelector("#element")!
  .getBoundingClientRect().top;
scrollHandler
  .between(0, elTop, () => {
    // ...
  })
  .onceOver(elTop, () => {
    // ...
  });

Reference

ScrollHandler arguments

const options: {
  target?: HTMLElement; // default: document.body
} = {}; // optional

const handler = new ScrollHandler(options);

ScrollHandler instance methods

• onScroll
  (effect: ScrollEffect) => this
  Send event to channel
• between
  (after: ScrollEventTarget, before: ScrollEventTarget, effect: ScrollEffect) => this
  Sets up conditional effect that runs between two scroll positions
• onceOver
  (after: ScrollEventTarget, effect: ScrollEffect) => this
  Sets up conditional effect that runs once when scroll position goes from less than to more than a given position
• onceUnder
  (before: ScrollEventTarget, effect: ScrollEffect) => this
  Sets up conditional effect that runs once when scroll position goes from more than to less than a given position
• when
  (condition: () => boolean, effect: ScrollEffect) => this
  Sets up conditional effect that runs when a given condition is met. Condition is checked on every scroll event.
• enable
  () => void
  Enables the scroll handler
• disable
  () => void
  Disables the scroll handler
• goTo
  (opts: GoToOptions) => this
  Scrolls to a given position

ScrollHandler instance properties

• scrollTop number
  The current scroll position
• target HTMLElement
  The target element

ScrollEffect

type ScrollEffect = (
  event: Event,
  utils: {
    getPercent: () => number; // <- Only available when using `between`
    disable: () => void;
  }
) => void;

ScrollEventTarget

type ScrollEventTarget = HTMLElement | number;

Source

The following is the entire library source, if you prefer - you can copy/paste this into a file in your project.

↗ Open in GitHub