Animation Parameters

Animation parameters define how your animations behave. They can be passed to the animate() function or used when creating animation instances.

Core Parameters

targets

TargetsParam

required

The element(s) to animate. This is the first argument to animate() and accepts multiple formats:

CSS Selector: '.my-element', '#box', 'div'
DOM Element: document.querySelector('.box')
NodeList: document.querySelectorAll('.boxes')
Array: [element1, element2, '.selector']
JavaScript Object: { x: 0, y: 0 }

Timing Parameters

duration

number | FunctionValue

default:"1000"

Animation duration in milliseconds.

// Fixed duration
animate('.box', { translateX: 250, duration: 2000 });

// Function-based duration
animate('.box', {
  translateX: 250,
  duration: (target, index, total) => {
    return (index + 1) * 500; // Each element takes longer
  }
});

delay

number | FunctionValue

default:"0"

Delay before animation starts in milliseconds.

// Fixed delay
animate('.box', { translateX: 250, delay: 500 });

// Staggered delay
animate('.box', {
  translateX: 250,
  delay: (target, index) => index * 100
});

loopDelay

number

default:"0"

Delay between loop iterations in milliseconds.

animate('.box', {
  translateX: 250,
  loop: 3,
  loopDelay: 500 // Wait 500ms between each loop
});

Playback Parameters

ease

EasingParam

default:"'outQuad'"

Easing function for the animation. Can be a string name or custom function.Built-in Easings:

'linear', 'none'
'in', 'out', 'inOut'
'inQuad', 'outQuad', 'inOutQuad'
'inCubic', 'outCubic', 'inOutCubic'
'inQuart', 'outQuart', 'inOutQuart'
'inQuint', 'outQuint', 'inOutQuint'
'inSine', 'outSine', 'inOutSine'
'inExpo', 'outExpo', 'inOutExpo'
'inCirc', 'outCirc', 'inOutCirc'
'inBounce', 'outBounce', 'inOutBounce'
'inBack', 'outBack', 'inOutBack'
'inElastic', 'outElastic', 'inOutElastic'

// String easing
animate('.box', { translateX: 250, ease: 'outElastic' });

// Custom easing function
animate('.box', {
  translateX: 250,
  ease: (t) => t * t * t // Cubic ease
});

// Function-based easing
animate('.box', {
  translateX: 250,
  ease: (target, index) => {
    return index % 2 === 0 ? 'outQuad' : 'outElastic';
  }
});

playbackEase

EasingParam

Easing applied to the entire animation timeline playback.

animate('.box', {
  translateX: 250,
  duration: 2000,
  playbackEase: 'inOutQuad' // Eases the entire animation
});

playbackRate

number

default:"1"

Speed multiplier for animation playback. Values > 1 speed up, < 1 slow down.

// Play at half speed
animate('.box', {
  translateX: 250,
  playbackRate: 0.5
});

// Play at double speed
animate('.box', {
  translateX: 250,
  playbackRate: 2
});

frameRate

number

default:"60"

Maximum frame rate for the animation in frames per second.

// Limit to 30fps
animate('.box', {
  translateX: 250,
  frameRate: 30
});

Loop Parameters

loop

number | boolean

default:"false"

Number of times to loop the animation. true or negative values create infinite loops.

// Loop 3 times
animate('.box', { translateX: 250, loop: 3 });

// Loop infinitely
animate('.box', { translateX: 250, loop: true });

alternate

boolean

default:"false"

Whether to alternate direction on each loop iteration.

animate('.box', {
  translateX: 250,
  loop: true,
  alternate: true // Goes back and forth
});

reversed

boolean

default:"false"

Whether to play the animation in reverse from the start.

animate('.box', {
  translateX: 250,
  reversed: true // Plays from end to start
});

Control Parameters

autoplay

boolean

default:"true"

Whether to automatically start the animation.

const anim = animate('.box', {
  translateX: 250,
  autoplay: false
});

// Manually start later
button.onclick = () => anim.play();

id

string | number

Custom identifier for the animation instance.

const anim = animate('.box', {
  id: 'myAnimation',
  translateX: 250
});

console.log(anim.id); // 'myAnimation'

Property Composition

composition

'none' | 'replace' | 'blend'

default:"'replace'"

How to compose with other animations on the same property.

'none': No composition, properties are independent
'replace': New animations replace old ones on the same property
'blend': New animations blend additively with existing ones

// First animation
animate('.box', { translateX: 100 });

// Second animation replaces the first
animate('.box', {
  translateX: 250,
  composition: 'replace' // Default
});

// Additive animation
animate('.box', {
  translateX: 100,
  composition: 'blend' // Adds to existing animations
});

modifier

(value: number) => number | string

Function to modify animated values before they’re applied.

animate('.box', {
  translateX: 250,
  modifier: (value) => Math.round(value) // Round to integers
});

// Add units
animate('.box', {
  translateX: 250,
  modifier: (value) => `${value}px`
});

Property Values

Animation parameters can include any animatable properties. Property values support multiple formats:

Number Values

animate('.box', {
  translateX: 250,
  opacity: 0.5,
  scale: 2
});

String Values with Units

animate('.box', {
  width: '100%',
  translateX: '250px',
  rotate: '1turn'
});

From-To Arrays

animate('.box', {
  translateX: [0, 250],    // From 0 to 250
  opacity: [1, 0]          // From 1 to 0
});

Multi-Value Arrays (Keyframes)

animate('.box', {
  translateX: [0, 100, 250, 100, 0], // Keyframe values
  duration: 2000
});

Object Values

animate('.box', {
  translateX: {
    to: 250,
    duration: 1000,
    ease: 'outQuad'
  },
  translateY: {
    from: 0,
    to: 100,
    delay: 500
  }
});

Function Values

animate('.box', {
  translateX: (target, index, total) => {
    return index * 100; // Different value per target
  },
  duration: 1000
});

Relative Values

animate('.box', {
  translateX: '+=250',  // Add 250 to current value
  translateY: '-=100',  // Subtract 100 from current value
  scale: '*=2'          // Multiply current value by 2
});

Keyframes

Duration-Based Keyframes

keyframes

DurationKeyframes

Array of keyframe objects, each with its own timing.

animate('.box', {
  keyframes: [
    { translateX: 100, duration: 500 },
    { translateY: 100, duration: 500, ease: 'outElastic' },
    { translateX: 0, duration: 500 },
    { translateY: 0, duration: 500 }
  ]
});

Percentage-Based Keyframes

keyframes

PercentageKeyframes

Object with percentage keys defining keyframe positions.

animate('.box', {
  duration: 2000,
  keyframes: {
    '0%': { translateX: 0, scale: 1 },
    '25%': { translateX: 100, scale: 1.2 },
    '50%': { translateX: 250, scale: 1.5 },
    '75%': { translateX: 100, scale: 1.2 },
    '100%': { translateX: 0, scale: 1 }
  }
});

Callbacks

onBegin

(anim: JSAnimation) => void

Called when the animation begins playing.

animate('.box', {
  translateX: 250,
  onBegin: (anim) => {
    console.log('Animation started');
  }
});

onUpdate

(anim: JSAnimation) => void

Called on every frame during the animation.

animate('.box', {
  translateX: 250,
  onUpdate: (anim) => {
    console.log('Progress:', anim.progress);
    console.log('Current time:', anim.currentTime);
  }
});

onComplete

(anim: JSAnimation) => void

Called when the animation completes.

animate('.box', {
  translateX: 250,
  onComplete: (anim) => {
    console.log('Animation finished');
    anim.targets[0].classList.add('done');
  }
});

onLoop

(anim: JSAnimation) => void

Called when the animation loops.

animate('.box', {
  translateX: 250,
  loop: true,
  onLoop: (anim) => {
    console.log('Loop iteration:', anim.currentIteration);
  }
});

onPause

(anim: JSAnimation) => void

Called when the animation is paused.

const anim = animate('.box', {
  translateX: 250,
  onPause: (anim) => {
    console.log('Animation paused at:', anim.currentTime);
  }
});

setTimeout(() => anim.pause(), 500);

onRender

(anim: JSAnimation) => void

Called when the animation renders to the DOM.

animate('.box', {
  translateX: 250,
  onRender: (anim) => {
    console.log('Rendered');
  }
});

onBeforeUpdate

(anim: JSAnimation) => void

Called before each update tick.

animate('.box', {
  translateX: 250,
  onBeforeUpdate: (anim) => {
    // Prepare for update
  }
});

Function Value Parameters

Many parameters accept functions that receive target information:

type FunctionValue = (
  target: Target,   // The current target element/object
  index: number,    // Index of the target (0-based)
  length: number    // Total number of targets
) => number | string | object

Example:

animate('.box', {
  translateX: (target, index, total) => {
    // Stagger positions based on index
    return index * 100;
  },
  delay: (target, index, total) => {
    // Stagger delays
    return index * 100;
  },
  duration: (target, index, total) => {
    // Vary duration
    return 500 + (index * 100);
  },
  ease: (target, index, total) => {
    // Alternate easing
    return index % 2 === 0 ? 'outQuad' : 'outElastic';
  }
});

animate() - Main animation function
Animation Class - Animation instance methods

Animation

Timeline

Timer

Animatable

Draggable

Utilities

Easings

​Core Parameters

​targets

​Timing Parameters

​duration

​delay

​loopDelay

​Playback Parameters

​ease

​playbackEase

​playbackRate

​frameRate

​Loop Parameters

​loop

​alternate

​reversed

​Control Parameters

​autoplay

​id

​Property Composition

​composition

​modifier

​Property Values

​Number Values

​String Values with Units

​From-To Arrays

​Multi-Value Arrays (Keyframes)

​Object Values

​Function Values

​Relative Values

​Keyframes

​Duration-Based Keyframes

​Percentage-Based Keyframes

​Callbacks

​onBegin

​onUpdate

​onComplete

​onLoop

​onPause

​onRender

​onBeforeUpdate

​Function Value Parameters

​Related

Build docs developers (and LLMs) love

Core Parameters

targets

Timing Parameters

duration

delay

loopDelay

Playback Parameters

ease

playbackEase

playbackRate

frameRate

Loop Parameters

loop

alternate

reversed

Control Parameters

autoplay

id

Property Composition

composition

modifier

Property Values

Number Values

String Values with Units

From-To Arrays

Multi-Value Arrays (Keyframes)

Object Values

Function Values

Relative Values

Keyframes

Duration-Based Keyframes

Percentage-Based Keyframes

Callbacks

onBegin

onUpdate

onComplete

onLoop

onPause

onRender

onBeforeUpdate

Function Value Parameters

Related