Skip to content

Animation

Animate model position and supported style channels, with promise-based sequencing.

#eles.animate(opts)

// Animate these elements' style and/or position to explicit targets over duration ms, easing the normalized time
eles.animate(opts: AnimateOptions): this

Animate these elements' style and/or position to explicit targets over duration ms, easing the normalized time.

There is no queue: the animation starts immediately, animations on disjoint channels run concurrently, and starting one that overlaps a running animation's channels stops the older one in place — its promise resolves, its values freeze, and the new animation captures from there. Sequence with await animation( …).play() rather than by queueing.

Animatable: position; opacity (both groups); node background-color/border-color/border-width, edge line-color; and the geometry numerics node width/height, edge width, compound padding and font-size. Colours interpolate in OKLab, matching the colour mappers.

Use named easings or cubic-bezier( …), CSS linear( …) and spring( bounce). A custom easing function is rejected — a closure cannot cross to the GPU, so accepting one would mean a curve that silently depended on whether the animation got offloaded.

Parameters
NameDescription
opts: AnimateOptions

targets (position, style, or collapsed for compound parents; viewport forms apply on cy.animate), duration, easing, delay, complete

Fields of opts
NameDescription
style: Record<string, string | number>?
position: Partial<Position>?
collapsed: boolean?

Target the collapsed state of compound parents. This is an element-only animation channel and may be combined with timing options, but not with other style, position, or viewport targets.

pan: Position?

viewport targets (core.animate)

panBy: Position?

viewport target: pan by a delta rather than to an absolute position. Resolved against the pan at creation time, so a manual pan afterwards does not move the target. Throws alongside pan — the two spell the same channel. Core-only: an element animation ignores it.

zoom: number?
fit: { eles?: unknown; boundingBox?: { x1: number; y1: number; x2?: number; y2?: number; w?: number; h?: number; }; padding?: number; }?

viewport target: animate to the viewport that fits the given elements (or an explicit model-space box). Resolved to pan/zoom when the animation is created.

center: { eles?: unknown }?

viewport target: animate the pan that centers the given elements

duration: number?
easing: string?

A named easing, cubic-bezier(), linear() or spring(bounce). For a spring, duration is the perceptual duration and the animation runs on past it to settle, so its total length is longer (see durationMs).

delay: number?
complete: () => void?
Returns this

this collection, for chaining; use animation() when you want the handle

Example

eles.animate({ position: { x: 20, y: 10 }, duration: 100 });
eles.stop(true);
console.log(cy.getElementById('a').position('x')); // 20

Example graph and handle setup

See

Collection#animation for the handle form with promise/pause/resume/reverse

#eles.animation(opts)

// Build an animation for these elements without starting it
eles.animation(opts: AnimateOptions): AnimationHandle

Build an animation for these elements without starting it.

Parameters
NameDescription
opts: AnimateOptions

the tween targets (position, style, or compound collapsed state) plus duration, delay, easing and complete

Fields of opts
NameDescription
style: Record<string, string | number>?
position: Partial<Position>?
collapsed: boolean?

Target the collapsed state of compound parents. This is an element-only animation channel and may be combined with timing options, but not with other style, position, or viewport targets.

pan: Position?

viewport targets (core.animate)

panBy: Position?

viewport target: pan by a delta rather than to an absolute position. Resolved against the pan at creation time, so a manual pan afterwards does not move the target. Throws alongside pan — the two spell the same channel. Core-only: an element animation ignores it.

zoom: number?
fit: { eles?: unknown; boundingBox?: { x1: number; y1: number; x2?: number; y2?: number; w?: number; h?: number; }; padding?: number; }?

viewport target: animate to the viewport that fits the given elements (or an explicit model-space box). Resolved to pan/zoom when the animation is created.

center: { eles?: unknown }?

viewport target: animate the pan that centers the given elements

duration: number?
easing: string?

A named easing, cubic-bezier(), linear() or spring(bounce). For a spring, duration is the perceptual duration and the animation runs on past it to settle, so its total length is longer (see durationMs).

delay: number?
complete: () => void?
Returns AnimationHandle

the handle; nothing runs until play()

Example

const handle = eles.animation({ position: { x: 20, y: 10 }, duration: 1 });
await handle.play();
console.log(handle.progress()); // 1

Example graph and handle setup

#eles.delay(duration, complete?)

// A no-op tween — a timed pause that touches no channels, so it composes with any running animation (use delayAnimation().play() + await to sequence)
eles.delay(duration: number, complete?: () => void): this

A no-op tween — a timed pause that touches no channels, so it composes with any running animation (use delayAnimation().play() + await to sequence).

Parameters
NameDescription
duration: number

the pause in ms

complete: () => void?

called when it elapses

Returns this

this collection, for chaining

Example

eles.delay(1);
eles.stop(true);
console.log(eles.animated()); // false

Example graph and handle setup

#eles.delayAnimation(duration, complete?)

// Like {@link delay}, but returns the handle instead of chaining
eles.delayAnimation(duration: number, complete?: () => void): AnimationHandle

Like delay, but returns the handle instead of chaining.

Parameters
NameDescription
duration: number

the pause in ms

complete: () => void?

called when it elapses

Returns AnimationHandle

the handle; nothing runs until play()

Example

const handle = eles.delayAnimation(1);
await handle.play();
console.log(handle.progress()); // 1

Example graph and handle setup

#eles.animated()

// True when any of these elements has a running animation
eles.animated(): boolean

True when any of these elements has a running animation.

Returns boolean

whether any element here is animating — not whether all are, and not whether the viewport is (that is cy.animated())

Example

console.log(eles.animated()); // false

Example graph and handle setup

#eles.stop(jumpToEnd?)

// Stop every running animation on these elements (animations have no queue)
eles.stop(jumpToEnd?: boolean): this

Stop every running animation on these elements (animations have no queue).

Parameters
NameDescription
jumpToEnd: boolean?Default: false

apply each animation's final values instead of freezing each channel where its tween reached

Returns this

this collection, for chaining

Example

eles.animate({ position: { x: 20, y: 10 }, duration: 100 });
eles.stop(true);
console.log(eles.animated()); // false

Example graph and handle setup

All guides · Alphabetical API index · Read continuously