Anime.js

To develop on the Anime.js repository, first install dependencies using npm i. You can then use the following scripts:

• npm run dev: Watches for changes in src/**/*.js, bundles the ESM version to lib/, and creates type declarations in types/.
• npm run dev:test: Runs dev and test:browser concurrently.
• npm run build: Bundles ESM, UMD, CJS, and IIFE versions to lib/ and creates type declarations in types/.
• npm run test:browser: Starts a local server and runs all browser-related tests.
• npm run test:node: Starts Node-related tests.
• npm run open:examples: Starts a local server to browse the examples locally.

Anime.js is a lightweight JavaScript animation library that works with CSS properties, SVG, DOM attributes, and JavaScript Objects. In V4, the library is used by importing ES modules.

import {
  animate,
  stagger,
} from 'animejs';

animate('.square', {
  x: 320,
  rotate: { from: -180 },
  duration: 1250,
  delay: stagger(65, { from: 'center' }),
  ease: 'inOutQuint',
  loop: true,
  alternate: true
});

Staggering allows you to apply delays or offsets to a collection of targets based on their index or position. Use StaggerParams to configure this behavior:

• from: The starting point for the stagger ('first', 'last', 'center', 'random', or an array of indices).
• start: The initial delay/offset.
• grid: For 2D staggering, provide an array of numbers representing the grid dimensions.
• axis: The axis to apply staggering on ('x', 'y', or 'z').
• jitter: Adds additive uniform noise. Use a number for flat +/-jitter or a tuple [start, end] to ramp the magnitude across the ordering.
• seed: Use a number or boolean to ensure reproducible random patterns.

// Conceptual usage of stagger parameters
const staggerConfig = {
  from: 'center',
  start: 10,
  grid: [10, 10],
  jitter: [0, 5],
  seed: 123
};

Staggering can be calculated based on the physical layout of elements rather than just their index in an array.

• grid: Pass an array like [columns, rows] to define a fixed grid. The stagger is calculated based on the distance from the from point within this grid.
• autoGrid: Set grid: true. Anime.js will attempt to calculate the bounding rectangles (getBoundingClientRect) of your targets to determine their positions in 2D or 3D space. The stagger is then calculated based on the actual spatial distance between elements.

When using Draggable, you can hook into the drag lifecycle by providing callback functions in the parameters object. Based on the internal implementation, the following lifecycle events are triggered:

• onDrag(draggable): Called during the movement phase when a drag is actively occurring.
• onSnap(draggable): Called when the element snaps to a defined snapX or snapY position.
• onRelease(draggable): Called after the release animation (including overshoot or spring physics) has completed or been triggered.

When using a Timeline, you can precisely control when an animation starts using TimelinePosition syntax:

• Number: Absolute position in milliseconds (e.g., 500).
• '+=Number': Add X ms after the previous element ends.
• '-=Number': Subtract X ms from the previous element's end.
• '*=Number': Position at a fraction of the total duration (e.g., '*=.5').
• '<': At the end of the previous element.
• '<<': At the start of the previous element.
• '<<+=Number': Relative to the start of the previous element.
• 'label': At a specific named label.
• stagger(value): Positions elements using a stagger pattern.

The Scope class provides a controlled environment for animations using the following mechanisms:

execute(cb)

Runs a callback function within the scope's context. While the callback is running, the global scope.current, scope.root, and globals.defaults are temporarily set to the scope's values. This ensures that any animation calls made inside the callback use the scope's configuration.

refresh()

Resets the scope by reverting all currently registered revertibles and revertConstructors, then re-running all registered constructors. This is automatically triggered when any mediaQueries defined during initialization change state.

revert()

Performs a full cleanup. It calls revert() on all registered items, executes all cleanup functions, removes media query event listeners, and clears all internal registries (methods, data, constructors, etc.).

The from parameter in stagger(val, params) determines where the animation sequence begins.

• 'first': Starts from the first element (default).
• 'last': Starts from the last element.
• 'center': Starts from the middle of the target collection.
• 'random': Shuffles the stagger values so they appear random.
• Number: A specific index to start from.
• Array [x, y, z]: For spatial staggers (when using grid: true or autoGrid), provides normalized coordinates (0 to 1) for the starting position.

A Timeline is a specialized Timer that acts as a container for other Renderable objects (like JSAnimation or other Timer instances).

Key behaviors:

• Automatic Duration: The timeline's duration is not fixed; it grows automatically as children are added via add(), set(), call(), or sync().
• Composition: When composition: true is set (default), adding children triggers an initialization process that ensures the timeline and its children are correctly wired for rendering.
• Defaults: You can pass a defaults object to the constructor to apply common animation parameters (like duration or easing) to all children added to that timeline.
• Labels: Labels act as temporal anchors, allowing you to reference specific time points by name instead of absolute numbers.

Anime.js accepts various types of targets for animations:

• DOMTarget: An HTMLElement or SVGElement.
• JSTarget: A plain JavaScript object (Record<String, any>).
• TargetSelector: A string (CSS selector), a NodeList, or a direct Target.
• DOMTargetsParam: An array of DOMTargetSelector or a single selector.
• JSTargetsParam: An array of JSTarget or a single object.