russellsamora/scrollama
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.
