Scroll Spy

A library for subscribing to scroll events in the browser. Runs all your events in one requestAnimationFrame.

Installation

$ npm install @earthpeople/scroll-spy

or

$ yarn add @earthpeople/scroll-spy

Usage

// some-component.js
import { startScrollSpy } from "@earthpeople/scroll-spy";

const subscribe = startScrollSpy();

let scrolledPast100 = false;

subscribe("scroll", event => {
  if (event.scrollTop > 100) {
    scrolledPast100 = true;
  }
});

startScrollSpy will only start the event loop if it's not already running, but it will always return the subscription function.

Events

| Event | Returns | Fires | | --------------------- | -------------------------------------- | ----------------------------------- | | scroll | EventObject | On document scroll | | scrollY | scrollTop, scrollDelta | On vertical scroll | | scrollX | scrollLeft, scrollXDelta | On horizontal scroll | | scrollEnd | EventObject | When document stops scrolling | | scrollReachedEnd | atBottom, scrollTop, scrollDirection | When scroll reaches end of document | | scrollReachedTop | atTop, scrollTop, scrollDirection | When scroll reaches top | | scrollDirectionChange | EventObject | When scroll direction changes | | resize | EventObject | On window resize | | resizeEnd | EventObject | When window stops resizing |

EventObject

| key | type | value | | --------------- | -------- | ------------------------------------------------------- | | scrollTop | number | Pixels from top | | scrollLeft | number | Pixels from left | | scrollDirection | string | "up" or "down" | | atTop | bool | true if scroll position is 0 or less* | | atBottom | bool | true if scroll position is full scroll height or more* | | scrollHeight | number | Full scroll height of the document | | scrollDelta | number | Difference in scroll since last tick | | scrollXDelta | number | Difference in horizontal scroll since last tick | | vh | number | Viewport height in pixels | | vw | number | Viewport width in pixels | | orientation | string | "landscape" or "portrait" |

* This is to prevent false answers in browsers with elastic scroll, like Safari

Subscribing

startScrollSpy returns a subscribe function when called. Use that to add your listeners.

const subscribe = startScrollSpy();

You can also import the subscribe method directly.

import { subscribe } from '@earthpeople/scroll-spy`

You can listen to multiple event types in the same listener, but be aware that some event types only returns a select collection of values.

subscribe("scroll resize", ({ orientation }) => {
  console.log(orientation);
});

Unsubscribing

The subscribe method returns a new function when called. Use that function to unsubscribe.

const unsubscribe = subscribe("scrollReachedEnd", ({ scrollTop }) => {
  alert(`Wow! You scrolled ${scrollTop} pixels and reached the end`);

  // No need to listen to this event anymore
  unsubscribe();
});

You can also unsubscribe to all events or remove all listeners on a specific event

import { startScrollSpy, unsubscribeAll } from '@earthpeople/scroll-spy'

// add a few listeners
...

// unsubscribe from just the resize events
unsubscribeAll('resize')

// unsubscribe from ALL events
unsubscribeAll()

ES5

If you want to use a pre compiled es5-module, import from @earthpeople/scroll-spy/es5 instead.