Animation Timeline

Timeline animation system for creating complex animations with easing, looping, and callbacks

Overview

The Timeline animation system provides a powerful way to create complex animations in OpenTUI. It supports property animations, easing functions, looping, callbacks, and nested timelines.

Creating a Timeline

createTimeline()

Creates and registers a new timeline with the animation engine.

import { createTimeline } from "@opentui/core"

const timeline = createTimeline({
  duration: 2000,
  loop: true,
  autoplay: true,
  onComplete: () => console.log("Animation complete"),
  onPause: () => console.log("Animation paused")
})

options · TimelineOptions · default: "{}"

Configuration options for the timeline

Show properties

duration · number · default: "1000"

Total duration of the timeline in milliseconds

loop · boolean · default: "false"

Whether the timeline should loop indefinitely

autoplay · boolean · default: "true"

Whether to start playing the timeline immediately

onComplete · () => void

Callback fired when the timeline completes

onPause · () => void

Callback fired when the timeline is paused

timeline · Timeline

A new Timeline instance registered with the animation engine

Timeline Class

add()

Adds an animation to the timeline at a specific start time.

timeline.add(
  targetObject,
  {
    x: 100,
    y: 50,
    duration: 1000,
    ease: "outExpo",
    onUpdate: (animation) => console.log(animation.progress),
    onComplete: () => console.log("Animation finished")
  },
  0 // start time
)

target · any · required

The object or array of objects to animate. Can be any object with numeric properties.

properties · AnimationOptions · required

Animation properties and options

Show properties

duration · number · default: "1000"

Duration of the animation in milliseconds

ease · EasingFunctions · default: "linear"

Easing function to use. Available options:

• linear - No easing
• inQuad, outQuad, inOutQuad - Quadratic easing
• inExpo, outExpo - Exponential easing
• inOutSine - Sinusoidal easing
• outBounce, inBounce - Bounce easing
• outElastic - Elastic easing
• inCirc, outCirc, inOutCirc - Circular easing
• inBack, outBack, inOutBack - Back easing

loop · boolean | number · default: "false"

Whether to loop the animation. Can be:

• false - No looping
• true - Loop infinitely
• number - Loop a specific number of times

loopDelay · number · default: "0"

Delay in milliseconds between loop iterations

alternate · boolean · default: "false"

If true, animation reverses direction on alternate loops (ping-pong effect)

onUpdate · (animation: JSAnimation) => void

Callback fired on each frame of the animation

onComplete · () => void

Callback fired when the animation completes

onStart · () => void

Callback fired when the animation starts

onLoop · () => void

Callback fired on each loop iteration

[propertyName] · number

Any numeric property name can be animated by providing its target value

startTime · number | string · default: "0"

When to start the animation in milliseconds from the timeline start

this · Timeline

Returns the timeline instance for method chaining

once()

Adds a one-time animation that starts at the current timeline position and is automatically removed when complete.

timeline.once(box, {
  opacity: 0,
  duration: 500,
  ease: "outQuad"
})

target · any · required

The object to animate

properties · AnimationOptions · required

Animation properties (same as add() method)

this · Timeline

Returns the timeline instance for method chaining

call()

Adds a callback function to be executed at a specific time in the timeline.

timeline.call(() => {
  console.log("This executes at 1 second")
}, 1000)

callback · () => void · required

Function to execute

startTime · number | string · default: "0"

When to execute the callback in milliseconds from the timeline start

this · Timeline

Returns the timeline instance for method chaining

sync()

Synchronizes another timeline to start at a specific time in this timeline.

const subTimeline = new Timeline({ duration: 1000 })
timeline.sync(subTimeline, 500) // Start sub-timeline at 500ms

timeline · Timeline · required

The timeline to synchronize

startTime · number · default: "0"

When to start the synchronized timeline in milliseconds

this · Timeline

Returns the timeline instance for method chaining

play()

Starts or resumes playback of the timeline.

timeline.play()

this · Timeline

Returns the timeline instance for method chaining

pause()

Pauses playback of the timeline.

timeline.pause()

this · Timeline

Returns the timeline instance for method chaining

restart()

Restarts the timeline from the beginning.

timeline.restart()

this · Timeline

Returns the timeline instance for method chaining

update()

Manually updates the timeline by a delta time. This is typically called automatically by the animation engine.

timeline.update(16.67) // Update by ~16ms (60fps)

deltaTime · number · required

Time elapsed in milliseconds since last update

Timeline Properties

currentTime · number

Current playback position in milliseconds

isPlaying · boolean

Whether the timeline is currently playing

isComplete · boolean

Whether the timeline has completed playback

duration · number

Total duration of the timeline in milliseconds

loop · boolean

Whether the timeline loops

Timeline Engine

The global animation engine manages all timelines and integrates with the renderer.

engine.attach()

Attaches the engine to a CLI renderer to synchronize with frame updates.

import { engine } from "@opentui/core"

engine.attach(renderer)

renderer · CliRenderer · required

The renderer to attach to

engine.register()

Manually registers a timeline with the engine.

const timeline = new Timeline({ duration: 1000 })
engine.register(timeline)

timeline · Timeline · required

The timeline to register

engine.unregister()

Unregisters a timeline from the engine.

engine.unregister(timeline)

timeline · Timeline · required

The timeline to unregister

engine.clear()

Unregisters all timelines from the engine.

engine.clear()

JSAnimation Interface

The animation object passed to onUpdate callbacks.

targets · any[]

Array of objects being animated

progress · number

Current progress of the animation (0-1), after easing is applied

currentTime · number

Current timeline time in milliseconds

deltaTime · number

Time elapsed since last frame in milliseconds

Example: Complex Animation

import { createTimeline } from "@opentui/core"

const box = { x: 0, y: 0, opacity: 1 }

const timeline = createTimeline({
  duration: 3000,
  loop: true,
  onComplete: () => console.log("Loop complete")
})

// Move right
timeline.add(box, {
  x: 100,
  duration: 1000,
  ease: "outExpo"
}, 0)

// Move down while fading
timeline.add(box, {
  y: 50,
  opacity: 0.5,
  duration: 1000,
  ease: "inOutQuad"
}, 1000)

// Callback
timeline.call(() => {
  console.log("Halfway through!")
}, 1500)

// Fade back in
timeline.add(box, {
  opacity: 1,
  duration: 500,
  ease: "linear"
}, 2500)