useAnimate

v0.0.14testeddemo

Reactive Web Animations API wrapper for a single element. Exposes imperative controls (play, pause, reverse, finish, cancel) alongside reactive state (playState, currentTime, playbackRate, ...). The reactive state is synced via requestAnimationFrame only while the animation is running, so an idle animation costs nothing. SSR-safe: nothing touches the DOM until the element resolves.

Source Tests

Examples

const el = useTemplateRef<HTMLElement>('el');
const { playState, play, pause } = useAnimate(
  el,
  [{ transform: 'rotate(0)' }, { transform: 'rotate(360deg)' }],
  { duration: 1000, iterations: Infinity },
);

// Shorthand: third argument is the duration in milliseconds
useAnimate(el, { opacity: [0, 1] }, 500);

Demo

Loading demo…

Signature

export function useAnimate(
  target: MaybeComputedElementRef,
  keyframes: UseAnimateKeyframes,
  options?: number | UseAnimateOptions,
): UseAnimateReturn{ ... }

Parameters

Parameter	Type	Default	Description
`target`	`MaybeComputedElementRef`	—	Element to animate (reactive ref, getter, or element)
`keyframes`	`UseAnimateKeyframes`	—	Keyframes to animate, reactive
`options`?	`number \| UseAnimateOptions`	—	Duration in ms, or full options object

Returns

UseAnimateReturnSupport flag, the Animation instance, controls, and reactive state

Property	Type	Default	Description
`isSupported`	`Readonly<Ref<boolean>>`	—	Whether the Web Animations API is supported in the current environment
`animate`	`ShallowRef<Animation \| undefined>`	—	The underlying `Animation` instance, or `undefined` before it is created
`play`	`() => void`	—	Start or resume the animation
`pause`	`() => void`	—	Suspend playback of the animation
`reverse`	`() => void`	—	Reverse the playback direction of the animation
`finish`	`() => void`	—	Seek the animation to the end of its active duration
`cancel`	`() => void`	—	Abort the animation, clearing its effects
`pending`	`ComputedRef<boolean>`	—	Whether the animation is currently waiting for an asynchronous operation
`playState`	`ComputedRef<AnimationPlayState>`	—	The current playback state of the animation
`replaceState`	`ComputedRef<AnimationReplaceState>`	—	The current replace state of the animation
`startTime`	`WritableComputedRef<CSSNumberish \| number \| null>`	—	The scheduled time at which the animation should begin (writable)
`currentTime`	`WritableComputedRef<CSSNumberish \| null>`	—	The current time value of the animation in milliseconds (writable)
`timeline`	`WritableComputedRef<AnimationTimeline \| null>`	—	The timeline associated with the animation (writable)
`playbackRate`	`WritableComputedRef<number>`	—	The playback rate of the animation (writable)