`scroll-interactions`

Introduction

Easy scroll-driven interactions in the browser built on top of IntersectionObserver. Set a hidden trigger line in the browser viewport and see how one or more elements relate to it. This package tells you when an element is above, below or intersect the trigger line. If the element intersect the trigger it can also calculate the percent of completion relative to the element's top border.

Features

Zero dependencies, lightweight (4kb).
Get browser's scroll direction (downwards or upwards).
Get element position relative to the trigger line (above, intersect, below).
Get percent of completion relative to the target element's top border.
Unobserve target elements.
Change IntersectionObserver's root (defaults to browser viewport).
Access the original IntersectionObserver entry elements.
Disconnect IntersectionObserver.

Install

NPM

npm install --save scroll-interactions

CDN

<script src="https://unpkg.com/scroll-interactions/dist/scroll-interactions.iife.min.js"></script>

Quick start

<div class="box">box1</div>
<div class="box">box2</div>
<div class="box">box3</div>

import scroll_interactions from "scroll-interactions";

const observe_box = scroll_interactions({
  targets: ".box",
  trigger: 0.5,
});

observe_box
  .init()
  .observe(({ direction, position }) => {
    // direction: scroll direction
    // position: element position relative to the trigger
  });

Examples

Try those examples and inspect their index.html source code for more info.

API

Go to API page.

How it works

The observe() method works as callback handler of IntersectionObserver, it fires one time on first page load, then it fires only when a target element enter or exit the trigger line.

If progress: true and a target element intersect the trigger line, a scroll event listener is added to keep track of progress, when the element leave the trigger line the event listener is removed.

When you use unobserve option, all targets that has been unobserved will be cached, if scroll-interactions is re-initialize it'll not observe them again (see docs/unobserve example), you can also empty the cache if needed (read API for reference).

Browsers support

It works with all browser that support IntersectionObserver. For older browser make sure to add the official IntersectionObserver polyfill before creating a scroll_interactions instance.

Notes

It works even if the browser is zoomed.

At the moment support only vertical scrolling.

Inspired by scrollama.

pldg/scroll-interactions

scroll-interactions