Performant Scroll-driven Interactions – scrollama.js

scrollama.js is a JavaScript library to create scroll-driven interactions that use Intersection Observer API for performant scroll position detection.

Installation:

# NPM
$ npm install scrollama --save

How to use it:

1. Import the scrollama.js.

// ES Module
import scrollama from "scrollama";
// OR CommonJS
const scrollama = require("scrollama");
// OR Browser (exposes the scrollama global)
<script src="https://unpkg.com/scrollama"></script>

2. Create a new scrollama instance.

const myScroller = Scrollama();

3. The HTML structure.

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

4. Setup the scrollama.js instance.

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

5. All possible parameters:

myScroller.setup({
  // required
  // step elements that will trigger changes
  // string or HTMLElement[]
  step: '.scroll__text .step', // 
  // parent element for the scroll story (use if scrollama is nested in a HTML element with overflow set to scroll or auto)
  container: undefined,       
  // parent element for step selector
  parent: undefined,
  // used as the viewport for checking the visibility of the target
  root: undefined,
  // optional, default = 0.5
  offset: 0.5,       
  // whether to fire incremental step progress updates or not.
  progress: false,
  // the granularity of the progress interval, in pixels
  threshold: 4,
  // Only trigger the step to enter once then remove listener.
  once: false,  
  // optional, default = false       
  debug: false
             
})

6. Event handlers.

myScroller.setup(
 
  // ...
             
})
.onStepEnter(callback)
.onStepExit(callback)
.onStepProgress(callback) // { element: DOMElement, index: number, progress: number }

7. API methods.

myScroller.setup(
 
  // ...
             
})
// Get or set the offset percentage
myScroller.offsetTrigger(number)
// Get latest dimensions the browser/DOM
myScroller.resize()
// Resume observing for trigger changes
myScroller.enable()
// Stop observing for trigger changes.
myScroller.disable()
// Destroy the instance.
 myScroller.destroy()

Changelog:

v3.2.0 (11/09/2022)

• Built-in resize using resize observers.
• Custom offsets on steps with data attributes