useAnimate

Reactive Web Animations API wrapper. Drives element.animate() with Observable-based reactive state for playState, currentTime, playbackRate, and pending.

Demo

Web Animations API

idle

Reactive wrapper around element.animate() with play / pause / reverse controls.

playState

idle

currentTime

—

playbackRate

1x

pending

false

PlayReverseFinishCancel

Usage

Hook

import { useRef$ } from "@usels/core";
import { useAnimate } from "@usels/web";

function Component() {
  const el$ = useRef$<HTMLSpanElement>();
  const { playState$, play, pause } = useAnimate(
    el$,
    { transform: "rotate(360deg)" },
    1000
  );

  return (
    <div>
      <span ref={el$} style={{ display: "inline-block" }}>useAnimate</span>
      <p>{playState$.get()}</p>
      <button onClick={play}>Play</button>
      <button onClick={pause}>Pause</button>
    </div>
  );
}

Scope

import { createRef$ } from "@usels/core";
import { createAnimate } from "@usels/web";

function Component() {
  "use scope"
  const el$ = createRef$<HTMLSpanElement>();
  const { playState$, play, pause } = createAnimate(
    el$,
    { transform: "rotate(360deg)" },
    1000
  );

  return (
    <div>
      <span ref={el$} style={{ display: "inline-block" }}>useAnimate</span>
      <p>{playState$.get()}</p>
      <button onClick={play}>Play</button>
      <button onClick={pause}>Pause</button>
    </div>
  );
}

Custom Keyframes

Array, object, or Observable keyframes are all supported.

Hook

import { useRef$ } from "@usels/core";
import { useAnimate } from "@usels/web";
import { useObservable } from "@usels/core";

function Component() {
  const el$ = useRef$<HTMLDivElement>();

  // Object form (PropertyIndexedKeyframes)
  useAnimate(el$, { transform: "rotate(360deg)" }, 1000);

  // Array form
  useAnimate(el$, [{ transform: "rotate(0deg)" }, { transform: "rotate(360deg)" }], 1000);

  // Observable — effect updates when value changes
  const keyframes$ = useObservable([
    { clipPath: "circle(20% at 0% 30%)" },
    { clipPath: "circle(20% at 50% 80%)" },
  ]);
  useAnimate(el$, keyframes$, 1000);
}

Scope

import { observable } from "@usels/core";
import { createRef$ } from "@usels/core";
import { createAnimate } from "@usels/web";

function Component() {
  "use scope"
  const el$ = createRef$<HTMLDivElement>();

  // Object form (PropertyIndexedKeyframes)
  createAnimate(el$, { transform: "rotate(360deg)" }, 1000);

  // Array form
  createAnimate(el$, [{ transform: "rotate(0deg)" }, { transform: "rotate(360deg)" }], 1000);

  // Observable — effect updates when value changes
  const keyframes$ = observable([
    { clipPath: "circle(20% at 0% 30%)" },
    { clipPath: "circle(20% at 50% 80%)" },
  ]);
  createAnimate(el$, keyframes$, 1000);
}

Options

Pass a number as duration shorthand, or an options object with full configuration.

useAnimate(el$, keyframes, {
  duration: 1000,
  immediate: true, // auto-play on mount (default: true)
  commitStyles: false, // commit styles on finish (default: false)
  persist: false, // persist animation (default: false)
  onReady(animate) {
    console.log("ready", animate);
  },
  onError(e) {
    console.error(e);
  },
});

Delaying Start

Hook

import { useRef$ } from "@usels/core";
import { useAnimate } from "@usels/web";

function Component() {
  const el$ = useRef$<HTMLDivElement>();
  const { play } = useAnimate(
    el$,
    { opacity: [0, 1] },
    {
      duration: 1000,
      immediate: false,
    }
  );

  return (
    <>
      <div ref={el$} />
      <button onClick={play}>Start Animation</button>
    </>
  );
}

Scope

import { createRef$ } from "@usels/core";
import { createAnimate } from "@usels/web";

function Component() {
  "use scope"
  const el$ = createRef$<HTMLDivElement>();
  const { play } = createAnimate(
    el$,
    { opacity: [0, 1] },
    {
      duration: 1000,
      immediate: false,
    }
  );

  return (
    <>
      <div ref={el$} />
      <button onClick={play}>Start Animation</button>
    </>
  );
}

Type

Parameters

Parameter	Type	Description
target	MaybeEventTarget	-
keyframes	UseAnimateKeyframes	-
options	number | DeepMaybeObservable<UseAnimateOptions> | undefined (optional)	-

UseAnimateOptions

Option	Type	Default	Description
immediate	boolean	true	Start playing immediately on mount.
commitStyles	boolean	false	Commit final styles to the element on finish.
persist	boolean	false	Persist the animation.
playbackRate	number	1	Initial playback rate.
onReady	((animate: Animation) => void)	-	Called once the Animation instance is ready.
onError	((e: unknown) => void)	-	Called when an animation error occurs.
id	string	-	-
timeline	AnimationTimeline | null	-	-
composite	CompositeOperation	-	-
iterationComposite	IterationCompositeOperation	-	-
pseudoElement	string | null	-	-
delay	number	-	-
direction	PlaybackDirection	-	-
duration	string | number | CSSNumericValue	-	-
easing	string	-	-
endDelay	number	-	-
fill	FillMode	-	-
iterationStart	number	-	-
iterations	number	-	-
window	WindowSource	-	-

Returns

UseAnimateReturn

Name	Type	Description
animate$	ReadonlyObservable<Animation | null>	Current Animation instance.
play	Fn	-
pause	Fn	-
reverse	Fn	-
finish	Fn	-
cancel	Fn	-
pending$	ReadonlyObservable<boolean>	-
playState$	ReadonlyObservable<AnimationPlayState>	-
replaceState$	ReadonlyObservable<AnimationReplaceState>	-
startTime$	ObservablePrimitive<number | null>	-
currentTime$	ObservablePrimitive<number | null>	-
timeline$	Observable<AnimationTimeline | null>	-
playbackRate$	ObservablePrimitive<number>	-
isSupported$	ReadonlyObservable<boolean>	-

Source

View on GitHub