or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

animatable.md animation.md draggable.md easings.md engine.md index.md scope.md scroll.md svg.md text.md timeline.md timer.md utilities.md waapi.md

tile.json

WAAPI

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
}