janpaepke/scrollmagic

ScrollMagic is a small JavaScript library for building scroll-based interactions on a web page. It tells your code where an element sits relative to the viewport as the user scrolls, and fires events when that position changes. The README describes the current release as version 3, and points users of the older version 2 to a separate branch called v2-stable. It is written in TypeScript, ships with native types, has zero dependencies, and weighs around 6 kilobytes gzipped. The README is careful to set expectations: ScrollMagic does not animate anything by itself. It only gives you precise scroll-position data and events, which you then plug into your own animation, lazy loading, parallax effect, scroll-linked video, behavioural tracking, or anything else. For ready-made scroll animation, the README points readers at GSAP ScrollTrigger, Motion, and anime.js. It also notes that modern CSS has native scroll-driven animations, and positions itself as a complement that adds cross-browser support, callbacks, progress values, and state. Under the hood it is a wrapper around two browser APIs, IntersectionObserver and ResizeObserver, with shared observers, batched animation frames, and single-frame updates to keep performance steady. It works with any scroll container, vertical or horizontal scrolling, server-side rendering, and any framework, since it has no opinions about React, Vue, or vanilla JavaScript. A plugin system is mentioned for extending it. The core idea is that you define two zones: a container zone on the scroll container, and an element zone on the tracked element. A progress value moves from 0 to 1 as the element zone passes through the container zone, and the library fires enter, leave, and progress events along the way. The README gives two common configurations as mental models. Contain is the default when no element is set: progress runs while one fully contains the other, useful for scroll progress bars and parallax. Intersect is the default when an element is set: progress runs while the element overlaps the viewport, useful for enter and leave animations or class toggles. The README ends with a mapping table that shows how the native CSS view-timeline ranges (cover, contain, entry, exit) correspond to ScrollMagic option combinations, and a full options table covering element, elementStart and elementEnd insets, container, containerStart and containerEnd, vertical axis, and others. Installation is a single npm install scrollmagic@next, and a quick-start snippet shows attaching enter, leave, and progress handlers to a tracked element.