ScrollMagic — Scroll Interaction and Animation Library

Introduction

ScrollMagic is a JavaScript library that lets developers create scroll-driven interactions. It decouples scroll position from animation progress, enabling effects like element pinning, parallax, class toggling, and synchronized animations tied to the user's scroll position.

What ScrollMagic Does

• Triggers animations and class changes when elements enter or leave the viewport
• Pins elements in place during a defined scroll range
• Synchronizes animation progress with scroll position for parallax effects
• Supports both CSS animations and GSAP tweens as animation backends
• Provides a scene-based API where each scroll interaction is an independent unit

Architecture Overview

ScrollMagic uses a controller-scene pattern. A single Controller listens to scroll events on a container (typically the window). Scenes define trigger points, durations, and actions. When the scroll position enters a scene's range, the scene fires events and can delegate animation to GSAP or CSS transitions. The library uses requestAnimationFrame internally to batch scroll calculations and minimize layout thrashing.

Self-Hosting & Configuration

• Install via npm or include the script tag from a CDN
• Create a Controller instance bound to the scroll container
• Define scenes with trigger elements, offsets, and durations
• Attach animation plugins (GSAP, Velocity, or CSS) to scenes
• Use the addIndicators debug plugin during development to visualize trigger points

Key Features

• Scene-based architecture where each scroll interaction is self-contained and testable
• Pin support for sticky-scroll effects without CSS position-sticky limitations
• Works with any animation library or plain CSS transitions
• Responsive scene recalculation on window resize
• Lightweight core with optional plugins for indicators, GSAP, and Velocity

Comparison with Similar Tools

• GSAP ScrollTrigger — tightly integrated with GSAP and more actively maintained; ScrollMagic is animation-library-agnostic
• Locomotive Scroll — provides smooth virtual scrolling with parallax; ScrollMagic focuses on discrete scroll-triggered scenes without custom scroll behavior
• AOS (Animate On Scroll) — simpler reveal animations with data attributes; ScrollMagic offers full programmatic control over pinning and progress
• Intersection Observer API — native browser API for visibility detection; ScrollMagic adds pinning, duration-based progress, and animation synchronization on top

FAQ

Q: Is ScrollMagic still maintained? A: The library is stable and widely used, though active development has slowed. The API is mature and the v2.x release covers most scroll interaction needs.

Q: Can I use ScrollMagic without GSAP? A: Yes. ScrollMagic can toggle CSS classes, trigger callbacks, or work with any animation library. GSAP integration is an optional plugin.

Q: Does ScrollMagic work with React or Vue? A: Yes. Initialize the controller in a lifecycle hook or useEffect and clean up on unmount. Community wrappers also exist for React and Vue.

Q: How does ScrollMagic handle performance on mobile? A: It uses requestAnimationFrame and avoids forced layouts. For complex pages, limit the number of active scenes and use the destroy method for off-screen sections.

Sources

• https://github.com/janpaepke/ScrollMagic
• http://scrollmagic.io/