scrollama

You can install Scrollama via npm or include it via a script tag.

Important: As of version 1.4.0, the IntersectionObserver polyfill is not included. You must manually add a polyfill for cross-browser support if you need to support older browsers.

NPM Installation:

npm install scrollama --save

Importing:

import scrollama from "scrollama";
// or
const scrollama = require("scrollama");

CDN/Global (Old school):

<script src="https://unpkg.com/scrollama"></script>

To use Scrollama for basic step triggering, define your step elements in HTML and then instantiate the scroller in JavaScript.

HTML Structure:

<div class="step" data-step="a"></div>
<div class="step" data-step="b"></div>
<div class="step" data-step="c"></div>

JavaScript Setup:

const scroller = scrollama();

scroller
  .setup({
    step: ".step",
  })
  .onStepEnter((response) => {
    // response: { element, index, direction }
  })
  .onStepExit((response) => {
    // response: { element, index, direction }
  });

const scroller = scrollama();

scroller
  .setup({
    step: ".step",
  })
  .onStepEnter((response) => {
    // { element, index, direction }
  })
  .onStepExit((response) => {
    // { element, index, direction }
  });

Use these methods to manage the lifecycle and behavior of your scroller:

• offsetTrigger([number | string]): Get or set the offset percentage. Value must be between 0-1 or a string with "px" (e.g., "200px"). Returns the instance.
• resize(): Tells Scrollama to get latest dimensions. Note: Built-in resize observers make this mostly unnecessary, but it is useful if you manually update DOM elements.
• enable(): Resumes observing for trigger changes.
• disable(): Stops observing for trigger changes.
• destroy(): Removes all observers and callback functions.

Scrollama provides three main callback methods to respond to scroll position:

1. onStepEnter(callback): Fires when the top or bottom edge of a step enters the offset threshold.

   • Callback argument: { element: DOMElement, index: number, direction: string }
   • direction is 'up' or 'down'.

2. onStepExit(callback): Fires when the top or bottom edge of a step exits the offset threshold.

   • Callback argument: { element: DOMElement, index: number, direction: string }

3. onStepProgress(callback): Fires incremental progress updates if progress: true is set in .setup().

   • Callback argument: { element: DOMElement, index: number, progress: number, direction: string }
   • progress is the percent of completion (0 - 1).

You can override the global offset option for individual elements by adding a data-offset attribute directly to the step element in your HTML. This supports both decimal values (0-1) and pixel strings.

Example:

<div class="step" data-offset="0.25"></div>
<div class="step" data-offset="100px"></div>

Register callbacks to respond to scroll events. The callbacks receive a response object containing the element, the index of the step, and the scroll direction ('down' or 'up'). If progress is enabled, onStepProgress also receives a progress value (0 to 1).

Callback Response Object:

• element: The DOM node of the step.
• index: The index of the step in the sequence.
• direction: 'down' or 'up'.
• progress: (Only in onStepProgress) A value between 0 and 1.

Use these methods to manage the active state of the scroller:

• enable(): Activates the observers to start tracking scroll position.
• disable(): Disconnects observers to stop tracking.
• destroy(): Disconnects observers and resets all internal callbacks and state.
• resize(): Manually triggers an update to the observers (useful if the layout changes significantly).