janpaepke/ScrollMagic v3.0.0-beta.0

v3.0.0-beta.0 — ScrollMagic 3

on GitHub

ScrollMagic 3 is a ground-up rewrite in TypeScript. The API, architecture, and internals are entirely new.

Architecture

• Built on IntersectionObserver + ResizeObserver (no manual scroll math)
• One instance per element — no more Controller/Scene split
• Shared observers — all instances share a single ResizeObserver and a single rAF scheduler
• Single-frame updates — scroll → progress in one animation frame (no extra frame latency)
• Dual IntersectionObserver (enter + leave edges) for precise viewport detection
• Ordered execution queue ensures bounds → observer → progress runs in correct order every frame

API

• new ScrollMagic({ element, ...options }) — one call, self-contained
• Two-bounds model: trigger bounds (zone on scroll container) + element bounds (zone on element) define the active zone
• Three events: enter, leave, progress — each with direction, location, and access to the full instance via event.target
• Named position shorthands: 'here' (0%), 'center' (50%), 'opposite' (100%) for inset options
• Options accept numbers (px), strings ('50%', '20px'), named positions, or functions (size) => number
• All options are getters/setters and can be batch-updated via .modify()
• .subscribe() returns an unsubscribe function (in addition to .on()/.off())
• Plugin system with onAdd, onRemove, onModify lifecycle hooks
• Static defaults via ScrollMagic.defaultOptions()

What's gone from v2

• Controller (replaced by per-instance scroll container detection via ContainerProxy)
• Scene (replaced by ScrollMagic instance)
• Pin system
• Built-in animation support (use GSAP ScrollTrigger, Motion, or anime.js)
• Duration concept (replaced by element bounds + trigger bounds)
• jQuery plugin
• Indicator plugin (planned as separate package)

DX

• Native TypeScript — full type safety, exported types for options, events, plugins
• SSR safe — no browser APIs until instance creation
• Zero dependencies, ~6 kB gzipped
• Dev-only warnings via process.env.NODE_ENV (tree-shaken in production builds)
• Browserslist: Chrome 73+, Firefox 69+, Safari 13.1+, Edge 79+

Install

npm install scrollmagic@next

See the README for full documentation.