useAnimator@astryxdesign/core v0.7.5 · useAnimator

Usage

Experimental: this hook and everything exported from @astryxdesign/core/motion/experimental are outside the stable compatibility promise and may change or be removed in a patch release. A compositor animator for touch presentations: springs, scroll coasts and any closed-form curve are baked into Web Animations on the individual translate, rotate, scale and opacity properties, so motion keeps running while JavaScript is busy and never re-renders the component. A finger can catch any animation mid-flight and a new target keeps its velocity. Under prefers-reduced-motion, travel becomes UIKit’s cross-fade. The same subpath exports createAnimator for non-React code, the spring, rubber-band and cubic-bézier math, and the UIKit constants table as the read-only uikit namespace.

ts
import {useAnimator} from '@astryxdesign/core'

Best practices

GuidancePractices
Do

Take every spring, rate and threshold from uikit (for example uikit.springs.sheetDetent) so the motion matches UIKit and each value keeps its source.

Do

Hand the release velocity from the gesture to animate so the motion continues the finger’s throw.

Don't

Drive the same element’s translate, rotate, scale or opacity from CSS transitions or other animations at the same time.

Don't

Rely on this API from stable product code: it is experimental and may change in a patch release.

Parameters

ParamTypeDescription
options

Read on the first render only: starting values (identity by default, never read from the DOM), a pseudoElement such as ::backdrop, a clock, and the Reduced Motion preference.

Returns

FieldTypeDescription
ref(element: HTMLElement | null) => void

Callback ref for the animated element; stable for the component’s lifetime.

animator

The animator; stable. animate(targets, {spring, velocity}) springs to new values from the current presentation value and velocity, play(curves) bakes any closed-form curve, decay(velocities, {bounds}) coasts like a scroll view, set(values) writes a value for direct manipulation, stop() freezes in place, and get / getVelocity read the curves without touching the DOM.

Use with shadcn

Already using the shadcn registry workflow? Install the real Astryx package and a local public re-export. Component implementation source stays in Astryx.

This install URL expires with the draft preview.
bash
npx shadcn@4.19.0 add https://astryx-c7nhg0ysl-fbopensource.vercel.app/shadcn/hooks/use-animator.json