Timeline API

The Timeline component is the engine that builds an animation and calculates each frame's state in real time.

It manages an Animation instance generated with TrackUtils.gen and automatically queries frames based on its given time value. Timeline may be configured to periodically update the time value via setInterval, or the time value may be controlled elsewhere.

Import

Interface

Timeline is a React component.

Props

• Type: TimelineProps<State extends object = any>
• The optional generic type parameter State refers to the structure of the animation's state. Must be an object.

Properties for the Timeline component.

track

• Type: TrackRegion<State>[]
• Required

The array of regions that make up the animation.

track is passed into TrackUtils.gen() immediately after Timeline mounts, calculating the Animation. After Timeline initializes, it will not re-calculate the animation if track changes when avoidReload = true.

defaultState

• Type: State
• Required

The animation's default state. Must be an object.

defaultState is passed into TrackUtils.gen() immediately after Timeline mounts, calculating the Animation. After Timeline initializes, it will not re-calculate the animation if defaultState changes when avoidReload = true.

value

• Type: number
• Required

The current frame of the animation, in milliseconds.

Changing this prop triggers a refresh within Timeline that queries the animation and returns the current frame state via onUpdate asynchronously.

playing

• Type: boolean
• Required

Whether or not the animation is playing.

While true, the interval within Timeline will run (as specified by the interval prop) and trigger onTick callbacks.

playbackSpeed

• Type: number
• Default: 1

The timeline's playback speed multiplier.

1 plays the animation at regular speed, 2 plays at double speed, 0.5 plays at half speed, etc. Supply a negative number to play in reverse. For example, -2 plays backwards at double speed.

interval

• Type: number
• Default: 10

The number of milliseconds the interval within Timeline will be set to, roughly corresponding to how often onTick callbacks will be triggered.

This property implies a performance versus quality tradeoff: larger intervals will refresh the frame less frequently, causing choppier animations but using less resources, whereas smaller intervals will have smaller gaps between refreshes but a greater performance cost.

This property is an approximation, and will not match exactly with the values returned by onTick. There are unavoidable (but minor) delays caused by querying the animation object and React renders, so expect less precision at the millisecond level.

endBehavior

• Type: TimelineEndBehavior
• Default: "stop"

Describes how the engine will calculate frame states for time values greater than the length of the animation.

avoidReload

• Type: boolean
• Default: true
• Since: v1.1.0

Whether or not Timeline will rebuild the animation when references to track or defaultState change.

This property is true by default, meaning the animation will rebuild only when endBehavior, easing, interp, or resolver change. Changing track or defaultState will have no effect post-initialization.

Setting avoidReload to false can be helpful if you want an animation to change dynamically after the Timeline has already initialized.

Disabling this prop can have negative performance effects for your animation if track or defaultState are redefined on every render of your parent component. Be sure to define track and defaultState outside your render function or properly memoize them.

easing

• Type: EasingFunction
• Default: undefined

Sets the animation's default easing function.

If not defined, TrackUtils.gen will use its own default easing function.

interp

• Type: InterpolationFunction
• Default: undefined

Sets the animation's default interpolation function.

If not defined, TrackUtils.gen will use its own default interpolation function.

resolver

• Type: TrackLayerResolver<State>
• Default: undefined

Sets the animation's default layer resolver.

If not defined, TrackUtils.gen will use its own default layer resolver.

onTick

• Type: (event: TickEvent) => void
• Default: () => {}

If playing is true, this callback will fire approximately every interval.

event.value will be equal to the time value when the event was created. See TickEvent.

Useful if a parent component is storing the animation's time value as state:

onUpdate

• Type: (event: UpdateEvent<State>) => void
• Default: () => {}

Will fire with the current frame state according to value whenever value changes.

See UpdateEvent.

Useful if a parent component is storing the animation's frame state:

onEnded

• Type: () => void
• Default: () => {}

Will fire when value is greater than or equal to the length of the track or when value is less than zero.

May trigger more than once.

onLoad

• Type: (event: LoadEvent<State>) => void
• Default: () => {}

Will fire when Timeline initializes, returning the Animation calculated by TrackUtils.gen().

See LoadEvent.

Timeline will initialize when it is mounted and whenever the following props change:

• endBehavior
• easing
• interp
• resolver

If avoidReload = false, Timeline will also initialize whenever these props change:

• track
• defaultState