tessl/npm-animejs

Fast, multipurpose JavaScript animation library for CSS, SVG, DOM, and JS objects with timelines, scroll triggers, physics, and interactive draggables

Overview

Eval results

Files

WAAPI

Name: tessl/npm-animejs
Author: tessl

Web Animations API wrapper providing compatibility layer and utilities for working with native browser animations.

Capabilities

waapi.animate Function

Create Web Animations API animation with enhanced control and anime.js compatibility.

/**
 * Create Web Animations API animation
 * Wrapper around native element.animate() with enhanced features
 * @param targets - DOM elements to animate
 * @param params - WAAPI animation parameters
 * @returns WAAPIAnimation instance
 */
function waapi.animate(
  targets: DOMTargetsParam,
  params: WAAPIAnimationParams
): WAAPIAnimation;

Usage Example:

import { waapi } from "animejs/waapi";

// Create WAAPI animation
const animation = waapi.animate(".box", {
  translateX: [0, 250],
  rotate: [0, 360],
  duration: 2000,
  ease: "outQuad",
});

// Control playback
animation.pause();
animation.resume();
animation.seek(1000);

WAAPIAnimation Class

Web Animations API wrapper with unified control interface.

/**
 * WAAPIAnimation class wrapping native Web Animations API
 */
class WAAPIAnimation {
  // ===== Properties =====

  /**
   * Array of target DOM elements
   */
  targets: DOMTargetsArray;

  /**
   * Array of native Animation instances (one per target)
   */
  animations: Array<Animation>;

  /**
   * Total animation duration in milliseconds
   */
  duration: number;

  /**
   * Whether animation is currently paused
   */
  paused: boolean;

  /**
   * Whether animation has completed
   */
  completed: boolean;

  /**
   * Whether animation is reversed
   */
  reversed: boolean;

  /**
   * Persist animation effects after completion
   * If true, styles remain after animation ends
   */
  persist: boolean;

  // ===== Getters/Setters =====

  /**
   * Current animation time in milliseconds
   * @settable Set to seek to specific time
   */
  currentTime: number;

  /**
   * Animation progress (0-1)
   * @settable Set to seek to percentage
   */
  progress: number;

  /**
   * Playback speed multiplier
   * @settable Set to change playback rate
   */
  speed: number;

  // ===== Callbacks =====

  /**
   * Called when animation completes
   */
  onComplete: Callback<WAAPIAnimation>;

  // ===== Methods =====

  /**
   * Play animation forward
   * @returns WAAPIAnimation instance for chaining
   */
  play(): WAAPIAnimation;

  /**
   * Pause animation
   * @returns WAAPIAnimation instance for chaining
   */
  pause(): WAAPIAnimation;

  /**
   * Resume paused animation
   * @returns WAAPIAnimation instance for chaining
   */
  resume(): WAAPIAnimation;

  /**
   * Restart animation from beginning
   * @returns WAAPIAnimation instance for chaining
   */
  restart(): WAAPIAnimation;

  /**
   * Reverse animation direction
   * @returns WAAPIAnimation instance for chaining
   */
  reverse(): WAAPIAnimation;

  /**
   * Alternate playback direction
   * @returns WAAPIAnimation instance for chaining
   */
  alternate(): WAAPIAnimation;

  /**
   * Seek to specific time
   * @param time - Time in milliseconds or percentage string
   * @param muteCallbacks - Suppress callbacks during seek
   * @returns WAAPIAnimation instance for chaining
   */
  seek(time: number | string, muteCallbacks?: boolean): WAAPIAnimation;

  /**
   * Cancel animation and remove effects
   * @returns WAAPIAnimation instance for chaining
   */
  cancel(): WAAPIAnimation;

  /**
   * Commit animated styles to elements as inline styles
   * @returns WAAPIAnimation instance for chaining
   */
  commitStyles(): WAAPIAnimation;

  /**
   * Complete animation immediately, jumping to end
   * @returns WAAPIAnimation instance for chaining
   */
  complete(): WAAPIAnimation;

  /**
   * Revert animation and remove all effects
   * @returns WAAPIAnimation instance for chaining
   */
  revert(): WAAPIAnimation;

  /**
   * Iterate over native animations
   * @param callback - Function called for each animation
   * @returns WAAPIAnimation instance for chaining
   */
  forEach(callback: (animation: Animation, index: number) => void): WAAPIAnimation;

  /**
   * Promise-like interface for completion
   * @param callback - Function called on completion
   * @returns WAAPIAnimation instance for chaining
   */
  then(callback: (animation: WAAPIAnimation) => void): WAAPIAnimation;
}

Usage Examples:

import { waapi } from "animejs/waapi";

// Create animation
const anim = waapi.animate(".element", {
  opacity: [0, 1],
  translateY: [50, 0],
  duration: 1000,
  ease: "outQuad",
});

// Playback control
anim.play();
anim.pause();
anim.resume();
anim.restart();
anim.reverse();

// Seeking
anim.seek(500); // Seek to 500ms
anim.seek("50%"); // Seek to 50%
anim.currentTime = 750; // Set current time
anim.progress = 0.8; // Set to 80% progress

// Speed control
anim.speed = 2; // 2x speed
anim.speed = 0.5; // Half speed

// Callbacks
anim.onComplete = (a) => {
  console.log("Animation complete");
};

// Promise-like
anim.then((a) => {
  console.log("Finished!");
});

waapi.convertEase Function

Convert anime.js easing function to CSS linear() format for use with Web Animations API.

/**
 * Convert easing function to CSS linear() string
 * Samples easing function and creates CSS linear() representation
 * @param easingFunction - Easing function to convert
 * @param samples - Number of sample points (default: 100)
 * @returns CSS linear() function string
 */
function waapi.convertEase(
  easingFunction: EasingFunction,
  samples?: number
): string;

Usage Example:

import { waapi, eases, spring } from "animejs";

// Convert built-in easing
const cubicEasing = waapi.convertEase(eases.outCubic);
// Returns: "linear(0, 0.09, 0.16, ..., 1)"

// Convert spring easing
const springEasing = waapi.convertEase(
  spring({ mass: 1, stiffness: 100, damping: 10 })
);

// Use with native element.animate()
element.animate(
  { transform: ["translateX(0)", "translateX(100px)"] },
  {
    duration: 1000,
    easing: springEasing, // Use converted easing
  }
);

// Use with waapi.animate
waapi.animate(".box", {
  translateX: 100,
  duration: 1000,
  ease: spring({ bounce: 0.4 }),
});

WAAPI Animation Configuration

Configure Web Animations API animations:

waapi.animate(".element", {
  // Animation properties
  translateX: [0, 250],
  rotate: [0, 360],
  opacity: [0, 1],
  scale: [1, 1.5],

  // Timing
  duration: 2000,
  delay: 500,
  endDelay: 300,

  // Easing (supports anime.js easings)
  ease: "outQuad",
  // or
  ease: eases.outElastic(1, 0.3),
  // or
  ease: spring({ bounce: 0.5 }),

  // Direction
  direction: "alternate",

  // Iterations
  iterations: 3, // Number of times to repeat
  // or
  iterations: Infinity, // Loop forever

  // Fill mode
  fill: "forwards", // 'none', 'forwards', 'backwards', 'both'

  // Persist after completion
  persist: true,

  // Callback
  onComplete: (anim) => {
    console.log("Done!");
  },
});

Multiple Targets

Animate multiple elements with WAAPI:

waapi.animate(".boxes", {
  translateY: [0, 100],
  rotate: [0, 180],
  duration: 1500,
});

// Access individual animations
const anim = waapi.animate(".boxes", {
  scale: [1, 1.2],
  duration: 1000,
});

anim.forEach((nativeAnim, index) => {
  console.log(`Animation ${index}:`, nativeAnim);
});

Seeking and Progress

Control playback position:

const anim = waapi.animate(".element", {
  translateX: 250,
  duration: 2000,
});

// Seek by time
anim.seek(1000); // Jump to 1 second
anim.currentTime = 1500; // Set time directly

// Seek by progress
anim.seek("75%"); // Jump to 75%
anim.progress = 0.5; // Set to halfway

// Get current position
console.log(anim.currentTime); // Current time in ms
console.log(anim.progress); // Current progress 0-1

Speed Control

Change playback speed:

const anim = waapi.animate(".element", {
  rotate: 360,
  duration: 3000,
});

anim.speed = 2; // Double speed
anim.speed = 0.5; // Half speed
anim.speed = -1; // Reverse playback

Persist and Commit Styles

Control style persistence after animation:

// Persist styles after animation
const anim = waapi.animate(
  ".element",
  {
    opacity: 0,
    translateX: 100,
    duration: 1000,
  },
  {
    persist: true, // Keep styles after completion
  }
);

// Or commit styles as inline styles
anim.then((a) => {
  a.commitStyles(); // Commits animated values as inline styles
});

Cancel and Revert

Remove animation effects:

const anim = waapi.animate(".element", {
  translateX: 250,
  rotate: 360,
  duration: 2000,
});

// Cancel removes effects immediately
anim.cancel();

// Revert also cleans up
anim.revert();

Integration with Scroll

Synchronize WAAPI with scroll:

import { onScroll, waapi } from "animejs";

// Create WAAPI animation without autoplay
const anim = waapi.animate(
  ".header",
  {
    opacity: [1, 0],
    translateY: [0, -50],
    duration: 1000,
  },
  { autoplay: false }
);

// Link to scroll
onScroll({
  target: ".header",
  sync: true,
  linked: anim,
});

Easing Conversion

Convert anime.js easings for WAAPI:

import { waapi, eases, spring, cubicBezier } from "animejs";

// Convert built-in easing
const outQuad = waapi.convertEase(eases.outQuad);

// Convert spring
const springEase = waapi.convertEase(
  spring({
    mass: 1,
    stiffness: 200,
    damping: 15,
  })
);

// Convert cubic bezier
const customBezier = waapi.convertEase(cubicBezier(0.68, -0.55, 0.265, 1.55));

// Use converted easings
waapi.animate(".element", {
  translateX: 100,
  duration: 1000,
  ease: springEase,
});

WAAPI vs JSAnimation

Comparison of WAAPI and standard anime.js animations:

import { animate, waapi } from "animejs";

// Standard JSAnimation (anime.js engine)
const jsAnim = animate(".box", {
  translateX: 250,
  duration: 1000,
  ease: spring({ bounce: 0.4 }),
});

// WAAPI animation (browser engine)
const waapiAnim = waapi.animate(".box", {
  translateX: 250,
  duration: 1000,
  ease: spring({ bounce: 0.4 }),
});

// WAAPI benefits:
// - Runs on separate thread (better performance)
// - Hardware accelerated
// - Continues during main thread blocking

// JSAnimation benefits:
// - More features (stagger, function values, etc.)
// - Consistent across browsers
// - More flexible property control

Complex WAAPI Patterns

Staggered WAAPI Animations

import { waapi } from "animejs";

const elements = document.querySelectorAll(".item");

elements.forEach((el, i) => {
  waapi.animate(el, {
    opacity: [0, 1],
    translateY: [50, 0],
    duration: 800,
    delay: i * 100, // Manual stagger
    ease: "outQuad",
  });
});

Looping with Alternate

waapi.animate(".loader", {
  rotate: 360,
  scale: [1, 1.2, 1],
  duration: 1500,
  iterations: Infinity,
  direction: "alternate",
  ease: "inOutQuad",
});

Sequential WAAPI Animations

waapi
  .animate(".box", {
    translateX: 100,
    duration: 500,
  })
  .then(() => {
    return waapi.animate(".box", {
      translateY: 100,
      duration: 500,
    });
  })
  .then(() => {
    return waapi.animate(".box", {
      rotate: 360,
      duration: 800,
    });
  });

Synchronized Animations

const anim1 = waapi.animate(".element1", {
  translateX: 250,
  duration: 2000,
});

const anim2 = waapi.animate(".element2", {
  translateY: 250,
  duration: 2000,
});

// Synchronize controls
function pause() {
  anim1.pause();
  anim2.pause();
}

function resume() {
  anim1.resume();
  anim2.resume();
}

Performance Optimization

WAAPI provides better performance for certain animations:

// Use WAAPI for smooth, long-running animations
waapi.animate(".background", {
  translateX: [0, -1000],
  duration: 20000,
  iterations: Infinity,
  ease: "linear", // Smooth continuous motion
});

// WAAPI is hardware-accelerated for these properties:
// - transform (translate, rotate, scale)
// - opacity
// Best performance when animating only these properties

Types

/**
 * WAAPI animation parameters
 */
interface WAAPIAnimationParams {
  /** Animation duration in milliseconds */
  duration?: number;

  /** Delay before animation starts */
  delay?: number;

  /** Delay after animation ends */
  endDelay?: number;

  /** Number of iterations (or Infinity) */
  iterations?: number;

  /** Playback direction */
  direction?: "normal" | "reverse" | "alternate" | "alternate-reverse";

  /** Easing function or string */
  ease?: EasingParam | string;

  /** Fill mode */
  fill?: "none" | "forwards" | "backwards" | "both";

  /** Persist styles after completion */
  persist?: boolean;

  /** Composite mode */
  composite?: "replace" | "add" | "accumulate";

  /** Animation properties */
  [property: string]: any;
}

/**
 * DOM targets parameter type
 */
type DOMTargetsParam =
  | string
  | HTMLElement
  | SVGElement
  | NodeList
  | Array<HTMLElement | SVGElement>;

/**
 * DOM targets array type
 */
type DOMTargetsArray = Array<HTMLElement | SVGElement>;

/**
 * Easing function type
 */
type EasingFunction = (time: number) => number;

/**
 * Easing parameter type
 */
type EasingParam = string | EasingFunction | Spring;

/**
 * Callback function type
 */
type Callback<T> = (instance: T) => void;

/**
 * Native Web Animations API Animation interface
 */
interface Animation {
  currentTime: number;
  playbackRate: number;
  playState: string;
  play(): void;
  pause(): void;
  reverse(): void;
  cancel(): void;
  finish(): void;
  // ... other native Animation methods
}

Install with Tessl CLI