Usage Guide

This guide covers the core concepts and controls for creating and managing animations with tween.js.

The Animation Loop

tween.js does not run on its own. You need to explicitly call the update() method in your main animation loop. This is typically done with requestAnimationFrame for the best performance.

import { update } from '@tweenjs/tween.js';

function animate(time) {
    requestAnimationFrame(animate);
    update(time); // This single call updates all active tweens
}

requestAnimationFrame(animate);

The update function takes an optional time parameter. If you don't provide it, it uses performance.now() automatically. Providing a time is useful for syncing tweens with other time-based systems, like a video player.

Creating a Tween

A tween animates the properties of a JavaScript object. To create one, instantiate the Tween class with the object you want to animate.

import { Tween } from '@tweenjs/tween.js';

const position = { x: 100, y: 0 };
const tween = new Tween(position) // Create a tween for the 'position' object
    .to({ x: 200, y: 100 }, 1000); // Animate to new values over 1000ms

Controlling the Tween

Once a tween is created, you have several methods to control its playback.

start() and stop()

A tween does not begin immediately after creation. You must call .start().

tween.start();

To stop an animation before it completes, use .stop().

tween.stop();

pause() and resume()

You can pause a running tween and resume it later.

// Pause the tween at the current time
tween.pause();

// Resume it from where it was paused
tween.resume();

chain()

To start one tween after another completes, use the .chain() method. You can chain multiple tweens to start simultaneously after the first one finishes.

const tweenA = new Tween(coords).to({ x: 100 }, 500);
const tweenB = new Tween(coords).to({ y: 100 }, 500);

// Start tweenB after tweenA completes
tweenA.chain(tweenB);
tweenA.start();

To create an infinite loop, chain them back to each other:

tweenA.chain(tweenB);
tweenB.chain(tweenA);
tweenA.start();

repeat() and yoyo()

To make a tween repeat, use the .repeat() method. It takes the number of additional repetitions.

tween.repeat(5); // Repeats 5 times after the first run, for 6 total runs
tween.repeat(Infinity); // Repeats forever

When combined with repeat(), .yoyo(true) will make the animation reverse direction on each repetition, like a yoyo.

tween.repeat(Infinity).yoyo(true);

delay() and repeatDelay()

Use .delay() to add a pause before the tween starts.

tween.delay(500); // Wait 500ms before starting

Use .repeatDelay() to add a pause between repetitions.

tween.repeat(3).repeatDelay(200); // Wait 200ms between each repeat

Callbacks

tween.js provides callbacks to execute code at different points in a tween's lifecycle.

• onStart(object): Runs once before the tween starts, after any delay.
• onEveryStart(object): Runs each time a tween starts, including on repeats.
• onUpdate(object, elapsed): Runs on every frame of the animation.
• onRepeat(object): Runs when a repetition is about to begin.
• onComplete(object): Runs once when the tween finishes normally (not when stopped).
• onStop(object): Runs when the tween is explicitly stopped with .stop().

Example:

const tween = new Tween({ x: 0 })
    .to({ x: 100 }, 1000)
    .onStart(() => {
        console.log('Animation started!');
    })
    .onUpdate((obj) => {
        console.log(`Current x value: ${obj.x}`);
    })
    .onComplete(() => {
        console.log('Animation finished!');
    })
    .start();