v3.0.0-beta.3

Breaking Changes

• Options renamed — scrollParent → container, triggerStart → containerStart, triggerEnd → containerEnd. This groups container-related options under a shared prefix and avoids confusion with GSAP's trigger (which refers to the element, not the container). The resolvedBounds getter now returns { element, container } instead of { element, scrollParent }.

New Features

• Multi-match selector warning (dev mode) — when a CSS selector passed to element or container matches more than one DOM element, a warning advises creating one instance per element instead.

Build

• Original sources embedded in source maps — published .map files now contain the actual TypeScript source via inlineSources, making them useful for debugging without the src/ directory.
• TypeDoc setup — API documentation can now be generated via npm run docs:api.

Docs

• Comprehensive JSDoc added to all public API surfaces (classes, methods, types, enums).
• Animated GIF diagrams for contain and intersect modes.

v3.0.0-beta.2

Breaking Changes

• destroy() calls onDestroy instead of onRemove on plugins — onRemove now only fires via removePlugin(). Plugins that used onRemove for destroy cleanup should add onDestroy (or assign the same function to both).
• computedOptions removed — replaced by resolvedBounds, which returns { element: ElementBounds, scrollParent: ContainerBounds } (cached layout bounds only, no longer leaks the full internal options structure).
• Getter return types narrowed — element, scrollParent, and vertical getters now return resolved types (Element, Window | Element, boolean) instead of the raw public input union. Setters still accept the full public types.

New Features

• Plugin lifecycle hooks: onEnable, onDisable, onDestroy — plugins can react to enable/disable transitions and distinguish manual removal from instance teardown. destroy() on an enabled instance fires onDisable → onDestroy in sequence.
• scrollmagic/util subpath export — exposes agnosticValues and agnosticProps via import { ... } from 'scrollmagic/util' for plugin authors working with direction-agnostic bounds.
• ElementBounds, ContainerBounds, ResolvedBounds types exported — available from the main entry point for plugin and integration authors.

Plugin Authoring Guide

See the new PLUGINS.md for the full plugin authoring guide, including lifecycle hook sequencing and utility usage.

Install

npm install scrollmagic@next

See the README for full documentation.

v3.0.0-beta.1

New Features

• scrollVelocity getter — per-container scroll velocity in px/s, shared across all instances on the same scroll parent via ContainerProxy. Returns 0 when disabled, destroyed, or idle (100ms staleness decay).
• enable() / disable() — temporarily disconnect all observers without destroying the instance. Progress freezes at its current value; modify(), on()/off(), plugins, and most getters remain functional. Re-enabling reconnects everything and schedules a full recalculation.
• { once: true } event listener option — follows the DOM addEventListener options bag pattern. Works with both .on() and .subscribe().
• refresh() / refreshAll() / destroyAll() — force bounds recalculation after layout changes invisible to ResizeObserver (position shifts, class toggles, sibling DOM mutations, font loading, etc.).
• Post-destroy and non-browser guards — all public methods now warn in dev mode and bail cleanly instead of producing undefined behavior when called after destroy() or outside a browser environment.
• Element–scrollParent ancestry validation (dev mode) — console.error when the tracked element isn't a descendant of its scroll parent, catching silent IntersectionObserver misconfiguration.

Bug Fixes

• Container position not initialized synchronously — non-window containers defaulted to {top:0,left:0} until the first scroll/resize event, producing wrong initial progress for containers offset from the viewport top.
• Zero-size container guard — when a scroll container collapses to 0px, updateProgress() no longer produces incorrect values (division by near-zero) and updateViewportObserver() no longer passes broken margins to the IntersectionObserver.
• Direction change not invalidating elementBoundsCache — changing vertical via modify() left stale axis-dependent bounds in the cache.
• containerBounds not rescheduled on option changes — triggerStart, triggerEnd, and vertical changes via modify() didn't trigger a container bounds recalculation, causing wrong progress and viewport margins.
• Stale closure in onElementResize — updateElementBoundsCache() replaced the entire bounds object, but the resize handler's destructured reference pointed to the old one, so size comparisons always returned false and progress never recalculated after element resize.
• destroy() skipping plugin onRemove callbacks — plugin cleanup was routed through removePlugin(), which hit the guardInert() check (destroyed was already true) and silently skipped all onRemove callbacks.

Performance

• Replace debounce with throttleRaf for container resize — removes the arbitrary 100ms debounce delay. Both window and element resize paths now use rAF-batched throttling for consistent, responsive behavior.
• Cache PixelConverter results — elementStart/elementEnd converters are skipped when element size is unchanged (common during scroll). Bounds caches mutated in-place via Object.assign instead of allocating new objects each frame.

Internal

• Explicit type keyword on type-only imports for better tree-shaking.
• New Vector type for {x, y} pairs, replacing the old ScrollDelta shape.
• E2e tests reorganized from origin-based to feature-based structure. 13 regression tests covering v2-reported edge cases added.
• Added MAINTAINING.md and ROADMAP.md.

Install

npm install scrollmagic@next

See the README for full documentation.

v3.0.0-beta.0 — ScrollMagic 3

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.

v2.0.9 — Final v2 release

Final v2 release. ScrollMagic v2 is no longer actively maintained and has been replaced by ScrollMagic 3.0.

project management:

• updated: all dev dependencies to latest versions
• removed: gulp-header dependency (replaced with inline transform to resolve lodash.template vulnerability)
• removed: gulp-json-editor dependency (syncVersion rewritten to be idempotent)
• removed: Travis CI configuration (no longer in use)
• fixed: build compatibility with yargs 18, del 8, open 11, gzip-size 7, pretty-bytes 7
• fixed: test suite compatibility with Jasmine 6 and GSAP 3
• fixed: syncVersion gulp task now only writes files when content actually changes
• fixed: deduplicated keywords in package.json and bower.json
• added: npm run build script

v2.0.8

added support for gsap 3

v2.0.6 - Revival Release

corrected version no

v2.0.5

built v2.0.5

ScrollMagic 2.0.0

Finally ScrollMagic 2.0.0 is released!
Besides being standalone there are many other changes.
Check out the changelog to see them.

v1.3.0 - Major Release

Refer to Changelog for details.