animate

Drive the Web Animations API reactively with typed keyframes.


Package	`@vizejs/composable/animate`
Own the source	`vize lib pull composable:animate`
Runtime exports	`useAnimate`
Gzip budget	3072 B

Usage

import { useAnimate } from "@vizejs/composable/animate";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useAnimate`	dom	experimental	deterministic-fallback	stable	caller, reactive-scope	web, desktop	`window`	`resolveElement`, `tryOnScopeDispose`

API

`useAnimate`

Drive the Web Animations API reactively with typed keyframes. Keyframe property names are checked against CSSStyleDeclaration, so typos are compile errors. Changing keyframes updates the running effect in place. Playback state is synced after every control call, on finish/cancel/ remove, and every animation frame while running. The animation is cancelled when the owning reactive scope stops. Nothing runs during server rendering (playState is "idle").

function useAnimate( target: MaybeElementTarget, keyframes: MaybeRefOrGetter<AnimationKeyframes | null>, options: number | UseAnimateOptions, ): AnimateControls

Types

`AnimateFrameHost`

Frame scheduler used to keep currentTime in sync while running.

Member	Type	Description
`requestAnimationFrame`	`(callback: FrameRequestCallback) => number`	Schedule a callback before the next repaint.
`cancelAnimationFrame`	`(handle: number) => void`	Cancel a scheduled frame.

`UseAnimateOptions`

Options for useAnimate.

Member	Type	Description
`immediate`?	`boolean`	Start playing as soon as the element resolves.
`commitStyles`?	`boolean`	Commit the final computed styles to the element's `style` on finish.
`persist`?	`boolean`	Keep the animation from being auto-removed by the browser when it is replaced by another filling animation.
`onReady`?	`(animation: Animation) => void`	Called once the animation object is created.
`onError`?	`(error: unknown) => void`	Called when creating the animation throws (e.g. invalid keyframes).
`frameHost`?	`MaybeRefOrGetter<AnimateFrameHost \| null \| undefined>`	Frame scheduler used to sync `currentTime` while running.

`AnimateControls`

Reactive animation state returned by useAnimate.

Member	Type	Description
`isSupported`	`Readonly<Ref<boolean>>`	Whether the resolved element supports `animate()`. `false` during server rendering.
`animation`	`Readonly<ShallowRef<Animation \| null>>`	Underlying `Animation`, once created.
`playState`	`Readonly<Ref<AnimationPlayState>>`	Playback state.
`pending`	`Readonly<Ref<boolean>>`	Whether a play/pause is pending.
`currentTime`	`WritableComputedRef<number \| null>`	Current time in milliseconds (writable to seek).
`playbackRate`	`WritableComputedRef<number>`	Playback rate (writable).
`play`	`() => void`	Play (creating the animation if needed).
`pause`	`() => void`	Pause.
`reverse`	`() => void`	Reverse the playback direction.
`finish`	`() => void`	Jump to the end.
`cancel`	`() => void`	Cancel and clear effects.