Skip to content

Animations

Animations use immediate channels and handles rather than a queue.

#Channels, concurrency and sequencing

Animations start immediately and have no queue. Animations on disjoint channels can run together. When a new animation overlaps a running animation's channels, the older one stops in place, its values freeze, and the new tween captures from those values. To sequence work, wait for a handle's promise and then create or play the next handle.

const node = cy.getElementById('a');
const move = node.animation(
{ position: { x: 180, y: 60 } },
{ duration: 300, easing: 'ease-in-out' },
);
await move.play();
await node.animation(
{ style: { 'background-color': '#d73027' } },
{ duration: 180 },
).play();

#Targets and easing

Collection animations target model-space position, the supported style channels and compound collapse state. Core animations target viewport state such as zoom and pan. Today the animatable style channels are opacity, selected node fills/borders, edge line color, node width/height, edge width, compound padding and font size, alongside position. Consult the API reference for the exact target shape and which channels apply to nodes, edges, parents or core.

Easing is declarative: use the documented named forms, a CSS cubic-bezier(… ) or linear(… ), or a spring( bounce ) specification. Easing callback functions are rejected so animation curves do not depend on whether a run is offloaded to a GPU. Colors interpolate in OKLab.

#Animation handles

animate() is the chaining form and returns the core/collection. animation() builds a handle without starting it. Handles expose play(), stop(), promise(), playing(), pause(), resume(), reverse() and read-only progress(). promise() resolves when the animation completes or is stopped; it is not a boolean completion-state query. Progress cannot be assigned or scrubbed.

#ani.play()

// Start immediately
ani.play(): Promise<void>

Start immediately.

Returns Promise<void>

resolves when the animation completes (or is stopped)

Example

await ani.play();
console.log(ani.progress()); // 1

Example graph and handle setup

#ani.stop(jumpToEnd?)

// Stop in place, or at the targets with jumpToEnd — the whole animation, whatever elements it spans
ani.stop(jumpToEnd?: boolean): void

Stop in place, or at the targets with jumpToEnd — the whole animation, whatever elements it spans. Through the manager, so a GPU-driven one releases its batch.

Parameters
NameDescription
jumpToEnd: boolean?Default: false

apply the final values instead of freezing

Returns void

Example

ani.play();
ani.stop(true);
console.log(ani.playing()); // false

Example graph and handle setup

#ani.promise()

// The completion promise
ani.promise(): Promise<void>

The completion promise.

Returns Promise<void>

resolves when the animation completes (or is stopped)

Example

ani.play();
await ani.promise();
console.log(ani.progress()); // 1

Example graph and handle setup

#ani.playing()

// Whether the animation is running and not paused
ani.playing(): boolean

Whether the animation is running and not paused.

Returns boolean

true while playing

Example

console.log(ani.playing()); // false

Example graph and handle setup

#ani.pause()

// Pause: freeze in place; the paused span leaves the timeline
ani.pause(): AnimationHandle

Pause: freeze in place; the paused span leaves the timeline.

Returns AnimationHandle

this handle, for chaining

Example

ani.play();
ani.pause();
console.log(ani.paused()); // true
ani.stop();

Example graph and handle setup

#ani.resume()

// Resume a paused animation with the clock shifted
ani.resume(): AnimationHandle

Resume a paused animation with the clock shifted.

Returns AnimationHandle

this handle, for chaining

Example

ani.play();
ani.pause();
ani.resume();
await ani.promise();
console.log(ani.progress()); // 1

Example graph and handle setup

#ani.reverse()

// Swap the tween's ends with elapsed remapped
ani.reverse(): AnimationHandle

Swap the tween's ends with elapsed remapped.

Returns AnimationHandle

this handle, for chaining

Example

ani.reverse();
await ani.play();
console.log(ani.playing()); // false

Example graph and handle setup

#ani.progress()

// Elapsed fraction of the duration (read-only — no scrubbing)
ani.progress(): number

Elapsed fraction of the duration (read-only — no scrubbing).

Returns number

the fraction in [0, 1]

Example

console.log(ani.progress()); // 0

Example graph and handle setup

#ani.paused()

// Whether the animation is paused
ani.paused(): boolean

Whether the animation is paused.

Returns boolean

true while paused

Example

console.log(ani.paused()); // false

Example graph and handle setup

#Stylesheet transitions

Stylesheet transitions use transition-property, transition-duration, transition-delay and transition-timing-function. Their transitionable set matches the documented animated channels. A sheet update supplies the new target style and animates the listed properties; the same channel concurrency rules apply. See styling for how declarative styles are resolved.

Moved sections

Migration guide

All guides · Alphabetical API index · Read continuously