Scrollama is a JavaScript library for scrollytelling that uses IntersectionObserver to detect when elements enter the viewport.
Scrollytelling—coordinating narrative text with animated graphics as users scroll—is difficult to implement performantly. Scrollama solves this by replacing scroll event listeners with IntersectionObserver, which fires callbacks when tracked elements enter or leave the viewport. This approach is more efficient because the browser handles position detection natively rather than recalculating on every scroll frame. The library provides a simple interface for defining steps (typically text sections) and triggering callbacks at specific scroll positions, allowing developers to update graphics or other content in response.
Scrollama suits projects that need scroll-driven interactives with minimal overhead. It works well for narrative-driven visualizations, data stories, and long-form content where graphics should update as readers scroll through text. The library is framework-agnostic and works with D3, React, or vanilla JavaScript. Developers should be aware that IntersectionObserver support varies across browsers; the library no longer includes a polyfill, so you must add one yourself if targeting older environments. The tool supports sticky graphics using CSS position properties, custom offsets per step via data attributes, and automatic resize handling through resize observers.
The project underwent significant refactoring in version 3.0 to simplify the codebase and improve maintainability. Built-in resize observer support and per-step custom offsets were added as new capabilities. The deprecated order option was removed, and earlier versions had deprecated container enter/exit callbacks in favor of CSS sticky positioning. The library maintains a stable API while evolving its internal architecture to ease future maintenance and feature development.
