@newswire/scroller

@newswire/scroller

Key features

• 🐜 Less than 600 bytes gzipped
• 👀 Uses a highly-performant Intersection Observer to monitor scrolling changes
• 🙅🏽‍ No dependencies (unless you need an Intersection Observer polyfill - check what browsers you support!)

Examples

• Basic
• Sticky graphic

Installation

@newswire/scroller

npm

npm install @newswire/scroller

You can also use it directly via unpkg.com.

You can also import it as a module via unpkg!

Usage

Assume for the following examples that our HTML is as follows:

To begin tracking the progression of the scenes, we need to set up our

Scroller

import Scroller from '@newswire/scroller';

// sets up the scroller instance, pass in an array of all the scenes
const scroller = new Scroller({
  scenes: document.querySelectorAll('.scene'),
});
// Scroller has a tiny event emitter embedded in it!
// the enter event is triggered every time a scene crosses the threshold
scroller.on('scene:enter', d => {
  d.element.classList.add('active');
});
// the exit event is triggered every time a scene exits the threshold
scroller.on('scene:exit', d => {
  d.element.classList.remove('active');
});
scroller.on('init', () => {
  console.log('Everything is ready to go!');
});
// starts up the IntersectionObserver
scroller.init();

If you need to additionally track the "container" of your scenes,

Scroller

import Scroller from '@newswire/scroller';

// sets up the scroller instance, pass in the container and an array of all the scenes
const scroller = new Scroller({
  container: document.querySelector('.container'),
  scenes: document.querySelectorAll('.scene'),
});
// the enter event works as you expect with scenes...
scroller.on('scene:enter', d => {
  d.element.classList.add('active');
});
scroller.on('scene:exit', d => {
  d.element.classList.remove('active');
});
// ...but if a container is passed, events fire for it as well!
scroller.on('container:enter', d => {
  console.log("Let's go!");
});
scroller.on('container:exit', d => {
  console.log('We are done here.');
});
scroller.init();

Intersection Observer's pre-check

This is a minor quirk of Intersection Observer to keep in mind. Whenever an element gets added to an Intersection Observer instance it is immediately checked for intersection. In the context of

Scroller

scene:exit

container:exit

*:enter

*:exit

Intersection Observer polyfill?

To keep the library lean,

@newswire/scroller

IntersectionObserver

There are a few good ways to ensure the polyfill is in place.

Load it within your bundle

The spec-based Intersection Observer polyfill is available on

npm

npm install intersection-observer

Once that is installed, you need to make sure that it is loaded before any code that'd depends on it will run. The polyfill is smart - it won't affect browsers who already have support!

import 'intersection-observer';
// or
require('intersection-observer');

// your awesome code here!

Load it with

polyfill.io

Before loading your scripts, you can include a link to

polyfill.io

polyfill.io

Load it with

unpkg.com

This is similar to the

polyfill.io

API

Table of Contents

• Scroller
  • Parameters
  • Properties
  • Examples
  • on
  • Parameters
  • Examples
  • off
  • Parameters
  • Examples
  • init
  • Examples
• Scroller#container:enter
  • Properties
• Scroller#scene:enter
  • Properties
• Scroller#container:exit
  • Properties
• Scroller#scene:exit
  • Properties
• Scroller#init

Scroller

Uses Intersection Observer to monitor the page location of a series of elements for scrollytelling.

Parameters

• options

  object

  • options.container

    Element? Optionally pass in what should be considered the containing element of all the scenes - this gets added to the Intersection Observer instance and additionally fires its own events

  • options.offset

    Number? How far from the top/bottom of the viewable area to trigger enters/exits of scenes, represented as a value between 0 and 1 (optional, default

    0.5

    )

  • options.scenes

    Array<Element> An array of all the Elements to be considered scenes of this Scroller

Properties

• observer

  (IntersectionObserver | null) Once initialized, a reference to the Scroller's instance of IntersectionObserver

Examples

import Scroller from '@newswire/scroller';

const scroller = new Scroller({
  scenes: document.querySelectorAll('.scenes'),
});
scroller.init();

on

Adds a callback to the queue of a given event listener.

Parameters

• type

  string Name of the event

• handler

  Function Callback function added to the listener

Examples

const scroller = new Scroller({
  scenes: document.querySelectorAll('.scenes')
});

const fn = (...) => {...};
// adds callback to listener
scroller.on('scene:enter', fn);

Returns void

off

Removes a callback from the queue of a given event listener.

Parameters

• type

  string Name of the event

• handler

  Function Callback function removed from the listener

Examples

const scroller = new Scroller({
  scenes: document.querySelectorAll('.scenes')
});

const fn = (...) => {...};
// adds callback to listener
scroller.on('scene:enter', fn);
// removes callback from listener
scroller.off('scene:enter', fn);

Returns void

init

Initializes a Scroller's IntersectionObserver on a page and begins sending any intersection events that occur.

Examples

const scroller = new Scroller({
  scenes: document.querySelectorAll('.scenes'),
});

scroller.init();

Returns void

Scroller#container:enter

Container enter event. Fires whenever the container begins intersecting.

Type: object

Properties

• bounds

  DOMRectReadOnly The bounds of the active element

• element

  Element The element that intersected

• index

  number This is always -1 on the container

• isScrollingDown

  boolean Whether the user triggered this element while scrolling down or not

Scroller#scene:enter

Scene enter event. Fires whenever a scene begins intersecting.

Type: object

Properties

• bounds

  DOMRectReadOnly The bounds of the active element

• element

  Element The element that intersected

• index

  number The index of the active element

• isScrollingDown

  boolean Whether the user triggered this element while scrolling down or not

Scroller#container:exit

Container exit event. Fires whenever the container has exited.

Type: object

Properties

• bounds

  DOMRectReadOnly The bounds of the exiting element

• element

  Element The element that exited

• index

  number This is always -1 on the container

• isScrollingDown

  boolean Whether the user triggering the exit while scrolling down or not

Scroller#scene:exit

Scene enter event. Fires whenever a scene has exited.

Type: object

Properties

• bounds

  DOMRectReadOnly The bounds of the exiting element

• element

  Element The element that exited

• index

  number The index of the exiting element

• isScrollingDown

  boolean Whether the user triggering the exit while scrolling down or not

Scroller#init

Init event. Fires once Scroller has finished setting up.

License

MIT