anime.js v4 — Administration & Architecture Guide

Executive Summary

anime.js v4.3.6 is a tree-shakeable JavaScript animation engine authored by Julian Garnier. It targets browsers and Node.js, providing CSS/SVG/DOM/object animation, timeline orchestration, scroll-driven animation, draggable interactions, FLIP-style layout transitions, text splitting, and a Web Animations API (WAAPI) bridge. The library ships as ES modules, CommonJS, UMD, and IIFE bundles with full TypeScript declarations. It has zero runtime dependencies; all dev tooling (Rollup, Mocha/Chai, BrowserSync, TypeScript) is devDependencies-only.

Architecture

High-Level Design

anime.js is structured as a layered class hierarchy built on a shared timing core with an intrusive linked-list data structure for managing children (tweens, animations, timelines).

┌─────────────────────────────────────────────────────┐
│                    Engine (singleton)                │
│         requestAnimationFrame / setImmediate         │
│              ┌──────────┴──────────┐                │
│              │   Linked-list of    │                │
│              │    active Timers    │                │
│              └──────────┬──────────┘                │
├─────────────────────────┼───────────────────────────┤
│  Timer ← Clock          │         Timeline ← Timer  │
│  JSAnimation ← Timer    │         WAAPIAnimation     │
├─────────────────────────┼───────────────────────────┤
│            Composition Layer (replace/none/blend)    │
├─────────────────────────────────────────────────────┤
│  Animatable  │  Draggable  │  ScrollObserver        │
│  AutoLayout  │  TextSplitter│  Scope                │
└─────────────────────────────────────────────────────┘

Class Hierarchy

Clock                         Base timing: deltaTime, fps, speed, requestTick()
├── Engine (singleton)        RAF loop, document visibility, timeUnit, precision
└── Timer                     Playback: play/pause/resume/reverse/seek/cancel/revert
    ├── JSAnimation           Property tweening, keyframes, composition, targets
    └── Timeline              Sequencing: add(), sync(), set(), label(), stretch()

Scope                         Framework integration, scoped cleanup, media queries
ScrollContainer               Scroll position tracking, resize observer
ScrollObserver                Scroll-linked playback (sync modes)
Animatable                    Reactive property animation (getter/setter pattern)
Draggable                     Pointer-driven drag with snap, bounds, inertia
AutoLayout                    FLIP-based layout animation
LayoutSnapshot                Captures DOM measurements for FLIP
TextSplitter                  Text segmentation (lines, words, chars)
WAAPIAnimation                Web Animations API bridge
DOMProxy                      Non-DOM target wrapper for Draggable
Transforms                    Matrix/transform resolution for Draggable
Spring                        Physics-based easing with mass/stiffness/damping

Module Map

The source is organized into 15 sub-packages under src/, each with its own index.js re-export:

Note

The src/types/ directory contains JSDoc type definitions only — no runtime code. TypeScript .d.ts files are generated from these via tsc -p tsconfig.types.json.

Package Exports Map

The library exposes 20 sub-path exports for fine-grained tree-shaking:

Each export provides types, require (CJS), import (ESM), and default (CJS fallback) conditions.

Internal Data Structures

Intrusive Linked Lists

The core data structure throughout anime.js is an intrusive doubly-linked list. Every parent-child relationship (Engine→Timer, Timer→Tween, Timeline→child, WAAPI composition lookups) uses the same pattern:

// Parent node
{ _head: firstChild, _tail: lastChild, _hasChildren: true }

// Child node
{ _prev: previousSibling, _next: nextSibling }

Operations are defined in src/core/helpers.js:

Important

The linked list operations use configurable property names (_prev/_next by default, _prevRep/_nextRep for composition siblings, _prevAdd/_nextAdd for additive blending chains). This allows a single tween node to participate in multiple linked lists simultaneously without extra wrapper objects.

Tween Types and Value Types

Tweens are classified by target type and value format:

Tween types (src/core/consts.js):

Value types:

Composition System

Three composition modes control how overlapping animations interact (src/animation/composition.js):

Caution

Known issue (#1138): addChild can create self-referential _prevRep/_nextRep links when re-adding an already-linked tween. This can cause infinite loops in composition resolution. Avoid rapidly starting the same animation instance while a previous run is still composing.

Rendering Pipeline

Engine Tick Loop

The Engine singleton (src/engine/engine.js) drives all animation:

1. engine.wake() — starts the RAF loop (or setImmediate in Node.js)
2. tickEngine() — recursive RAF callback:
   • If engine._head exists, request next frame and call engine.update()
   • Otherwise, set reqId = 0 (auto-sleep when no active animations)
3. engine.update():
   • requestTick(time) — framerate gating via Clock._scheduledTime
   • computeDeltaTime(time) — calculate time delta
   • Walk linked list of active tickables (_head → _next)
   • For each non-paused tickable: call tick() with computed time
   • Paused tickables: remove from engine, set _running = false, auto-cancel if completed
   • Call additive.update() for blend-mode composition

Per-Frame Render (src/core/render.js)

The render() function handles a single tickable per frame:

1. Time clamping — clamp absolute time to [-delay, duration]
2. Iteration calculation — compute current loop iteration (bitwise ~~ for performance)
3. Direction resolution — XOR of _reversed and (_alternate && isOdd) determines effective direction
4. Playback easing — optional _ease applied to iteration time
5. Callbacks — onBegin, onLoop, onBeforeUpdate fired at appropriate transitions
6. Tween rendering — walk child tweens via linked list:
   • Compute eased progress: tween._ease(time / duration)
   • Interpolate: lerp(fromNumber, toNumber, easedProgress)
   • For COLOR/COMPLEX types: interpolate each number component
   • Apply _modifier function
   • Set value on target based on tween type
7. Transform batching — CSS transforms are concatenated per-element into a single transform string (stored via transformsSymbol on the target), then applied once
8. Composition — for replace mode, resolved tweens overwrite; for blend mode, additive values are summed across the _prevAdd/_nextAdd chain

Note

Date.now is used instead of performance.now throughout. The source comments note it is "precise enough for timings calculations, performs slightly faster, and works in Node.js environment."

Document Visibility Handling

The engine automatically pauses on document.hidden and resumes on visibility restore (calling resetTime() on all children to prevent time jumps). This can be disabled via engine.pauseOnDocumentHidden = false.

Requirements & Compatibility

Runtime Requirements

Build Requirements

Configuration Reference

Engine Configuration

The engine singleton exposes these configuration surfaces:

Global Defaults

engine.defaults (alias for globals.defaults in src/core/globals.js):

Tip

Override defaults globally for your entire application:

import { engine } from 'animejs';
engine.defaults.duration = 500;
engine.defaults.ease = 'inOut(3)';
engine.timeUnit = 's'; // Switch to seconds globally

Build Configuration

The only environment variable is build (checked in rollup.config.js). When build=true, Rollup produces minified production bundles. The npm run build script sets this automatically.

Build & Development

npm Scripts

Build Output (dist/)

dist/
├── modules/           ES modules + CJS (per sub-package)
│   ├── index.js       Main ESM entry
│   ├── index.cjs      Main CJS entry
│   ├── index.d.ts     TypeScript declarations
│   ├── animation/
│   ├── timer/
│   ├── timeline/
│   ├── ...            (one directory per sub-path export)
│   └── waapi/
└── bundles/           Pre-built bundles
    ├── anime.umd.js
    ├── anime.umd.min.js
    ├── anime.iife.js
    └── anime.iife.min.js

Note

The "files" field in package.json restricts npm publish to the dist/ directory only. Source code under src/ is not included in the published package.

TypeScript Configuration

Two tsconfig files:

Testing

Test Architecture

Tests use Mocha (TDD interface) with Chai assertions. Two test environments:

Test suites live in tests/suites/ (31 files, 335,861 chars — the largest directory by character count).

Playground Tests

The tests/playground/ directory contains 20+ interactive test pages covering:

• Playback controls, keyframes, lerp, sandbox
• Layout (including clone variants)
• Timeline (nested, test sets, seek)
• ScrollObserver (onscroll with assets)
• Draggables (callbacks)
• WAAPI (composition, eases, playback, values)
• SVG motion path, scope, timekeeper
• Three.js instanced mesh, benchmark

These are manual/visual tests, not part of the automated suite.

Build Validation

tests/suites/build.test.js validates that all module entry points can be loaded without errors. It dynamically imports each sub-path export and catches module loading failures:

Error loading module ${path}: ${error.message}

Security Analysis

Attack Surface

anime.js is a client-side library with no network I/O, no file system access, and no eval/Function constructor usage. The attack surface is minimal:

Symbol-Based Caching

Target metadata is stored using Symbol keys (isRegisteredTargetSymbol, isDomSymbol, isSvgSymbol, transformsSymbol, morphPointsSymbol, proxyTargetSymbol) to avoid property name collisions with user objects.

CSS Variable Handling

CSS custom properties are parsed via cssVariableMatchRgx (/var\(\s*(--[\w-]+)(?:\s*,\s*([^)]+))?\s*\)/), which correctly extracts variable names and fallback values without executing them.

Operations & Performance

Memory Management

• No garbage collection pressure from tween objects: Tween decomposition reuses pre-allocated objects (fromTargetObject, toTargetObject) rather than creating new ones per frame.
• Linked list vs. array: Using intrusive linked lists for children means O(1) insert/remove without array shifting or splicing.
• Transform batching: CSS transforms are concatenated into a single string per element per frame, avoiding multiple style recalculations.
• Engine auto-sleep: When all animations complete and the linked list is empty, the RAF loop stops (reqId = 0), consuming zero CPU.

Performance Constants

Framerate Control

The Clock.requestTick(time) method implements frame gating:

requestTick(time) {
  if (time < this._scheduledTime) return tickModes.NONE; // Skip frame
  // Advance scheduled time by at least one frameDuration
  this._scheduledTime += frameDelta < frameDuration ? frameDuration : frameDelta;
  return tickModes.AUTO;
}

This allows per-animation fps caps. An animation with fps: 30 inside an engine running at 60fps will only update every other frame.

DevTools Integration

If window.AnimeJSDevTools is present at initialization, the engine registers with it:

• Each Timer/Animation registers via devTools.register(this, parameters, isInfinite)
• Infinite loops are capped to devTools.maxInfiniteLoops iterations in dev mode
• Multiple anime.js instances are tracked via window.AnimeJS array (each pushes a { version, engine } entry)

Module Deep-Dive

Core Module (src/core/)

The 11-file core module is the foundation everything else builds on:

Easing System (src/easings/)

The easing subsystem is modular with 7 sub-packages:

Spring physics: The Spring class uses a damped harmonic oscillator solver. It iterates until the spring settles within globals.precision tolerance, automatically computing the duration. The solver runs at construction time (not per-frame), producing a lookup-based easing function.

Scroll System (src/events/)

ScrollContainer: Wraps a scrollable element (or document.body for window scroll). Tracks scrollX, scrollY, dimensions, and scale. Uses ResizeObserver for dimension updates. Maintains its own linked list of ScrollObserver children.

ScrollObserver: Links a Timer/Animation/Timeline to scroll position. Sync modes:

Threshold parsing supports absolute pixels, viewport-relative percentages, and callback functions.

Layout System (src/layout/)

LayoutSnapshot: Captures DOM element positions (bounding rect, computed transforms, margins, padding) for FLIP calculation. Handles both regular elements and SVG.

AutoLayout: Implements FLIP (First-Last-Invert-Play) animation:

1. Capture "first" state via LayoutSnapshot
2. Apply DOM mutation
3. Capture "last" state
4. Compute delta (translate + scale)
5. Apply inverted delta as starting transform
6. Animate to identity

Supports enterFrom, leaveTo, and swapAt states for add/remove/reorder transitions. Internally creates a Timeline (or WAAPI animation) to drive the FLIP.

Draggable System (src/draggable/)

DOMProxy: Lightweight wrapper that gives plain objects a DOM-like interface (getBoundingClientRect, classList, x, y, width, height). Used for non-DOM draggable targets.

Transforms: Helper that resolves the current DOMMatrix for an element's parent chain, computes the inverse matrix, and converts screen-space pointer deltas to local-space deltas. This allows correct drag behavior on transformed/rotated/scaled elements.

Draggable: Full drag implementation with:

• Touch and mouse pointer handling
• Configurable axes (x, y, or both)
• Container bounds with overflow modes
• Snap points (grid-based or array-based)
• Momentum/inertia with spring-based settling
• Cursor management (grab/grabbing states)
• Event callbacks: onGrab, onDrag, onRelease, onSettle, onSnap, onUpdate

Uses Animatable internally for smooth animated property updates.

Text Splitting (src/text/)

TextSplitter: Segments text content into lines, words, and characters using Intl.Segmenter (with fallback to regex splitting). Features:

• Wraps segments in <span> elements with data-line, data-word, data-char attributes
• Clone mode: creates duplicate elements offset by top/bottom/left/right for reveal effects
• Wrap mode: adds overflow-hidden containers around each segment
• Template customization via class parameter
• Line detection: measures element positions post-split to group characters into actual rendered lines
• Preserves aria-hidden on decorative duplicates
• revert() restores original DOM

WAAPI Bridge (src/waapi/)

WAAPIAnimation: Translates anime.js animation parameters into native Element.animate() calls:

• Converts anime.js easing functions to CSS linear() strings via sampling
• Maps compositionTypes to WAAPI composite modes
• Manages a global linked list of active WAAPI animations for composition tracking
• Handles commitStyles() before cancellation to preserve final values
• Supports scroll-linked WAAPI via timeline sync

Easing conversion (parseWAAPIEasing): Caches converted easings in WAAPIEasesLookups. Native CSS timing functions (linear, ease, cubic-bezier(), steps()) pass through directly. Spring and custom easings are sampled to 100 points and converted to linear() strings.

Error Messages

The library produces very few runtime errors, all from specific modules:

Warning

getPath() in src/svg/helpers.js uses console.warn (not throw) when a selector doesn't resolve to a valid SVGGeometryElement. This means invalid SVG selectors fail silently with an undefined return rather than throwing.

Code Patterns & Conventions

Coding Style

Naming Conventions

Tree-Shaking Design

• "sideEffects": false in package.json
• /*#__PURE__*/ annotations on singleton IIFEs
• Each module re-exports only from its own index.js
• Sub-path exports allow importing only needed functionality
• No circular dependencies between sibling modules (all share core as common dependency)

Known Issues & Community Reports

Open Bugs (from GitHub Issues as of source commit)

Notable Feature Requests

Troubleshooting

Animations Not Starting

1. Check autoplay: Default is true, but if overridden globally via engine.defaults.autoplay = false, you must call .play() manually.
2. Scope cleanup: If using Scope, ensure the scope hasn't been reverted. Reverted animations are cancelled.
3. Engine paused: Check engine.paused. Tab visibility changes auto-pause the engine.
4. Zero duration: A duration of 0 or minValue creates a "setter" (instant jump), not an animation.

WAAPI Animations Disappearing

WAAPI animations call commitStyles() then cancel() when they finish (unless persist: true). If styles aren't sticking:

• Set persist: true to keep the WAAPI animation alive
• Check that commitStyles() isn't failing silently (wrapped in try/catch in source)

Transform Conflicts

anime.js batches all CSS transforms for an element into a single transform string per frame. If external code modifies element.style.transform between frames, those changes will be overwritten. Use anime.js for all transform manipulation on animated elements.

Spring Duration Calculation

Springs auto-calculate duration based on settling time. If animations appear to end too early or onComplete fires before visual settling:

• Increase globals.precision (default 4) for tighter convergence
• Adjust spring parameters (reduce stiffness, increase damping)
• Known issue #1118: perceived duration may not match calculated duration

Node.js Usage

anime.js detects non-browser environments via typeof window !== 'undefined'. In Node.js:

• requestAnimationFrame → setImmediate
• cancelAnimationFrame → clearImmediate
• DOM-specific features (CSS, SVG, scroll, text splitting, WAAPI) are unavailable
• Object property animation and timer/timeline features work normally

Quick Reference

Factory Functions

Timer/Animation Methods

Utility Functions

All chainable utilities support a fluent API via Proxy-based chaining:

import { clamp, round, mapRange } from 'animejs/utils';
const transform = mapRange(0, 100, -1, 1).clamp(-0.5, 0.5).round(2);
transform(75); // 0.5

Contributing

Repository Structure

src/                    Source modules (ES module)
├── core/               Foundation (11 files)
├── animation/          JSAnimation + composition
├── timer/              Timer base class
├── timeline/           Timeline sequencing
├── engine/             RAF loop singleton
├── animatable/         Reactive animation
├── draggable/          Drag interaction
├── events/             Scroll system
├── layout/             FLIP animations
├── scope/              Framework integration
├── text/               Text splitting
├── svg/                SVG utilities
├── waapi/              WAAPI bridge
├── easings/            Easing functions (7 sub-packages)
├── utils/              Math + DOM utilities
├── types/              JSDoc type definitions
└── index.js            Main barrel export
tests/
├── suites/             Automated tests (31 files)
├── playground/         Interactive visual tests
└── index.html          Browser test entry

Development Workflow

1. npm install — install dev dependencies
2. npm run dev — watch mode with auto-recompile
3. Make changes in src/
4. npm run test:browser — verify in browser
5. npm run test:node — verify in Node.js
6. npm run build — production build

Adding a New Module

1. Create directory under src/ with index.js re-export
2. Add sub-path export to package.json "exports" map (types, require, import, default)
3. Export from src/index.js if it should be in the main bundle
4. Add corresponding test file in tests/suites/
5. Rebuild to verify tree-shaking works correctly