Scrollama

Scrollama is a JavaScript library for scroll-driven storytelling that uses the browser's native IntersectionObserver API to trigger step-based callbacks and animations as the user scrolls through a page. It pins graphic elements using CSS sticky positioning while scrolling through associated text steps, enabling side-by-side narrative experiences without JavaScript-driven layout calculations.

The library provides a configurable offset threshold system that accepts a single global offset or per-element data-attribute offsets to define the viewport position that triggers step events. It reports scroll progress as a 0-1 ratio for driving continuous animations, and offers programmatic observer lifecycle management with start, stop, and remove methods to control when scroll observers are active. The library is resize-aware, recalculating element bounding boxes and viewport dimensions on window resize or DOM mutations to maintain accurate scroll tracking.

Scrollama supports iframe embedding by allowing a custom root element for scroll observation, and provides per-element offset customization through data attributes. It fires enter and exit callbacks when step elements cross configurable viewport thresholds, and reports step progress for fine-grained animation control. The library also includes observer destruction capabilities to clean up all listeners and callbacks.

Features

Scroll-Driven Animation Tools - A JavaScript library that triggers narrative steps and animations as the user scrolls through a page using IntersectionObserver.

Scroll-Driven Step Callbacks - Fires enter and exit callbacks when scroll positions cross configurable step boundaries for sequenced storytelling.

Scroll-Position Event Triggers - Fires callbacks when step elements enter or exit viewport thresholds for scroll-driven interactions.

Scroll-Offset Thresholds - Accepts a single global offset or per-element data-attribute offsets to define the viewport position that triggers step events.

Scroll Pinning Utilities - Pins graphic elements using CSS position sticky while scrolling through associated text steps.

Scroll Progress Mapping - Reports scroll progress as a 0-1 ratio for driving continuous animations based on element visibility.

Step Enter-Exit Callbacks - Fires enter and exit callbacks when step elements cross configurable viewport thresholds.

Scroll Trigger Distance Configurators - Fires callbacks when a scroll target reaches a configurable vertical offset from the viewport.

Graphic Pinning - Relies on CSS position: sticky to pin graphic elements while text steps scroll past, avoiding JavaScript-driven layout calculations.

Narrative Graphic Pinning - Pins graphic elements with CSS position sticky while scrolling through associated text steps for side-by-side narratives.

Scrollytelling Graphics - Pins graphic elements with CSS position sticky while scrolling through associated text steps for side-by-side narratives.

Scroll Step Detectors - Uses the browser's native IntersectionObserver API to detect when elements enter or exit viewport thresholds without polling scroll events.

Story Step Observers - Uses the IntersectionObserver API to detect when story steps enter the viewport for efficient scroll-based interactions.

Scroll Progress Ratios - Reports scroll progress as a 0-1 ratio of how far an element has moved through its observation threshold for fine-grained animation control.

Observer Lifecycle Management - Provides programmatic start, stop, and remove methods for scroll-trigger observers.

Step Trigger Offsets - Sets the viewport position that triggers step events using a percentage or pixel value.

Step Progress Reporting - Reports the percentage a step has scrolled through its threshold for fine-grained animation control.

Target Offset Configurators - Allows setting unique viewport offsets for individual step elements via data attributes.

Per-Element Offset Overrides - Ships per-element offset customization via data attributes for individual step elements.

Viewport Resize Handling - Recalculates element dimensions and viewport state on window resize or DOM mutations.

russellsamorascrollama

Features

Star history