ScrollMagic

ScrollMagic calculates progress (from 0 to 1) based on the relationship between two sets of bounds:

1. Container bounds: A zone on the scroll container defined by containerStart and containerEnd.
2. Element bounds: A zone on the tracked element defined by elementStart and elementEnd.

Progress is tracked as the element bounds pass through the container bounds.

The order in which hooks fire depends on how the instance is being stopped:

• removePlugin(plugin): Fires onRemove only.
• destroy() on an enabled instance:
  1. onDisable (tracking paused, observers disconnected)
  2. onDestroy (final cleanup)
• destroy() on a disabled instance: Only onDestroy fires.

Important: onRemove does not fire during destroy(). If your plugin requires the same cleanup logic for both removal and destruction, you should assign the same function to both hooks:

const cleanup = function (this: ScrollMagic) {
	/* ... */
};
const plugin: ScrollMagicPlugin = {
	name: 'shared-cleanup',
	onRemove: cleanup,
	onDestroy: cleanup,
};

When building plugins that need to support both vertical and horizontal scrolling, use the utilities provided in scrollmagic/util to handle direction-neutral properties and values.

• agnosticProps(vertical): Returns a map of direction-neutral prop names (like start, end, size) to their CSS/DOM equivalents (top/left, bottom/right, height/width, etc.).
• agnosticValues(vertical, obj): Extracts relevant values from an object (like a DOMRect) based on the scroll direction.

Example usage:

import { agnosticValues, agnosticProps } from 'scrollmagic/util';

// For vertical scrolling:
const values = agnosticValues(true, element.getBoundingClientRect());
// returns { start: rect.top, end: rect.bottom, size: rect.height, ... }

Import ScrollMagic and instantiate it with a target element. You can then chain .on() methods to listen for scroll events like enter, leave, and 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)}%`));

To use ScrollMagic in your project, install the @next version using npm:

npm install scrollmagic@next

Plugins extend ScrollMagic instances with custom behavior such as class toggles, debug overlays, or animation bindings. A plugin is a plain object that must include a name and can optionally implement lifecycle hooks. Inside these hooks, this is bound to the ScrollMagic instance the plugin is attached to.

To use a plugin, call sm.addPlugin(plugin) on your ScrollMagic instance.

import ScrollMagic, { type ScrollMagicPlugin } from 'scrollmagic';

const myPlugin: ScrollMagicPlugin = {
	name: 'my-plugin',
	onAdd() {
		// `this` is the ScrollMagic instance
		this.on('enter', () => {
			/* ... */
		});
	},
	onRemove() {
		this.off('enter' /* ... */);
	},
};

const sm = new ScrollMagic({ element: '#target' });
sm.addPlugin(myPlugin);
sm.removePlugin(myPlugin); // or let destroy() handle cleanup

For advanced offset calculations, you can provide a PixelConverter function instead of a number or string. A PixelConverter is a function that receives the current size of the element or container (in pixels) and returns a number representing the pixel offset to be used for position calculations.

This is useful for offsets that need to scale dynamically based on the container's size.

// A converter that always returns 10% of the container's size in pixels
const myConverter: PixelConverter = (size: number) => size * 0.1;

const options: Public = {
  containerStart: myConverter
};

You can extend ScrollMagic functionality by creating a Plugin object. Plugins receive lifecycle callbacks that are automatically triggered by the instance. All callbacks are optional and the this context is the owning ScrollMagic instance.

Available lifecycle hooks:

• onAdd: Called when added via addPlugin.
• onRemove: Called when removed via removePlugin.
• onEnable: Called when enable() is called.
• onDisable: Called when disable() is called.
• onDestroy: Called when destroy() is called.
• onModify: Called when options change via modify(). Receives only the changed options.