Guide · Open source
How to use ScrollMagic: track scroll position and fire events
Updated · written with AI from the project's own documentation and checked against our catalogue data
ScrollMagic is a JavaScript library that reports where an element sits relative to the viewport as the user scrolls, and fires events such as enter, leave and progress when that changes. It does not animate anything on its own, so you decide what to do with the data, such as toggling a class or driving an animation. This guide shows how to install it, create your first instance, and choose between the contain and intersect configurations.
ScrollMagicjanpaepke/ScrollMagic · ★ 15k · MIT Install options & downloads Quick start
- 1Install the package. Run npm install scrollmagic@next in your project to get the v3 release.
- 2Import ScrollMagic. Import the default export from the scrollmagic package into your JavaScript or TypeScript file.
- 3Pick the element to track. Pass a selector or element to the element option. Create one instance per element if you track several.
- 4Choose a configuration. Leave containerStart and containerEnd unset for intersect mode on an element, or use contain mode when element is null.
- 5Attach event handlers. Chain .on() with enter, leave or progress to run your code when scroll state changes.
- 6Use the data. Toggle a class, start an animation or lazy load content inside your handlers, since ScrollMagic only supplies the scroll data.
Install ScrollMagic with npm
ScrollMagic is installed through a package manager. The README lists Node.js as the prerequisite but does not state a minimum Node.js version. The current v3 release is published under the next tag, so install that tag explicitly.
This project is the v3 line. The legacy v2 version lives on a separate branch named v2-stable, so use that branch only if you need the old API.
npm install scrollmagic@nextCreate your first ScrollMagic instance
Import the library and pass an options object to the constructor. Here, the element is selected with a CSS selector. You then chain event handlers with .on(). The enter and leave events fire when the element's visibility state changes, and progress fires as the value changes.
Selectors match only the first element. To track several elements, create one instance per element.
- enter: fires when the element starts to intersect the viewport in intersect mode
- leave: fires when the element stops intersecting
- progress: gives a value from 0 to 1 through e.target.progress
import ScrollMagic from 'scrollmagic';
new ScrollMagic({ element: '#my-element' })
.on('enter', () => console.log('visible!'))
.on('leave', () => console.log('gone!'))
.on('progress', e => console.log(`${(e.target.progress * 100).toFixed(0)}%`));Understand container and element bounds
ScrollMagic defines an active range with two sets of bounds. Container bounds are a zone on the scroll container, set with containerStart and containerEnd. Element bounds are a zone on the tracked element, set with elementStart and elementEnd. Progress goes from 0 to 1 as the element bounds pass through the container bounds.
Inset values work like CSS top and bottom. Positive values offset inward from the edge in the tracked direction. You can use numbers in pixels, strings such as '50%' or '20px', named positions ('here', 'center', 'opposite'), or a function that receives the size and returns a number.
- Numbers are pixel values, for example 50
- Strings are percentage or pixel values, for example '50%'
- Named positions are 'here' (0%), 'center' (50%) and 'opposite' (100%)
- Passing null to element, container, containerStart or containerEnd resets it to the inferred default
Choose contain or intersect mode
Contain is the default when element is null. The container bounds match the viewport edges, so progress goes from 0 to 1 while one element fully contains the other. The README lists scroll progress bars, parallax, scroll-linked video and scroll-driven storytelling as typical uses.
Intersect is the default when element is set. The container bounds span the full viewport, so progress runs while the element intersects the viewport, from its leading edge entering to its trailing edge leaving. The README lists enter and leave animations, lazy loading, class toggles and visibility tracking as typical uses.
You can also set these values explicitly. For example, containerStart: 0 and containerEnd: 0 on an instance with an element gives contain behaviour. The README describes these as mental models rather than fixed modes.
Configure a horizontal or custom scroll container
The vertical option defaults to true. Set it to false to track horizontal scrolling. The container option defaults to window, but you can pass any scroll container as an element or a CSS selector.
Options can be passed to the constructor and changed later through setters or .modify(), so you do not need to create a new instance when a value changes.
- vertical: true for vertical scrolling (default), false for horizontal
- container: window (default), an Element, or a selector
What people use it for
- Toggling a CSS class when a section enters the viewport
- Lazy loading images as they approach the screen
- Driving a scroll progress bar with the progress value from 0 to 1
- Tracking which page sections a visitor reaches for analytics
- Building scroll-linked video or parallax effects with your own code
Frequently asked questions
Is ScrollMagic free to use?
Yes. The README lists the license as MIT and describes the project as free to use and open source. Check the LICENSE.md file in the repository for the full terms.
How do I install ScrollMagic?
Run npm install scrollmagic@next. The README uses this command for the current release under the next tag. It requires Node.js, though the README does not state a version.
Does ScrollMagic animate elements by itself?
No. The README says ScrollMagic provides scroll-position data and events, and what you do with them is up to you. For ready-made animation, the README points to GSAP ScrollTrigger, Motion, or anime.js.
Does ScrollMagic work with React or Vue?
The README says it is framework agnostic and works with React, Vue, vanilla JavaScript and other setups. It is used through JavaScript code, so you wire it into your components yourself.
How is ScrollMagic different from CSS scroll-driven animations?
Native scroll-driven animations are CSS-only and not yet supported in all browsers, according to the README. ScrollMagic adds cross-browser support, event callbacks, progress values and state management that the native API does not cover.
Can I use ScrollMagic to track horizontal scrolling?
Yes. Set the vertical option to false. The README lists horizontal and vertical scrolling as supported and vertical as the default.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
ScrollMagic suits developers who want precise scroll-position data and events without adopting a full animation toolkit, and who are comfortable writing JavaScript. If you want a ready-made animation timeline, the README points to GSAP ScrollTrigger, Motion, or anime.js, and if simple CSS effects are enough, native scroll-driven animations may cover them without a library.
Install options & downloads