Animation Timeline

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)

Core API

Text & Editing

Rendering

Input Handling

Layout

Advanced

Animation Timeline

Overview

Creating a Timeline

createTimeline()

Timeline Class

add()

once()

call()

sync()

play()

pause()

restart()

update()

Timeline Properties

Timeline Engine

engine.attach()

engine.register()

engine.unregister()

engine.clear()

JSAnimation Interface

Example: Complex Animation

Build docs developers (and LLMs) love

Core API

Text & Editing

Rendering

Input Handling

Layout

Advanced

​Overview

​Creating a Timeline

​createTimeline()

​Timeline Class

​add()

​once()

​call()

​sync()

​play()

​pause()

​restart()

​update()

​Timeline Properties

​Timeline Engine

​engine.attach()

​engine.register()

​engine.unregister()

​engine.clear()

​JSAnimation Interface

​Example: Complex Animation

Build docs developers (and LLMs) love

Overview

Creating a Timeline

createTimeline()

Timeline Class

add()

once()

call()

sync()

play()

pause()

restart()

update()

Timeline Properties

Timeline Engine

engine.attach()

engine.register()

engine.unregister()

engine.clear()

JSAnimation Interface

Example: Complex Animation