useEasing

About

useEasing animates a value between 0 and 1 and exposes controls for pausing, resuming, resetting, restarting, looping, and alternating direction. The exported Easing object provides linear, quadratic, and cubic presets.

Examples

import { Easing, useEasing, usePrefersReducedMotion } from "rooks";

export default function EasedMeter() {
  const reduceMotion = usePrefersReducedMotion();
  const [progress, controls] = useEasing(reduceMotion ? 1 : 1000, {
    autoStart: false,
    easing: Easing.easeInOutQuad,
  });

  return (
    <section>
      <progress max={1} value={progress}>
        Progress: {progress}
      </progress>
      <p>
        {controls.state}; completed {controls.endCount} time(s)
      </p>
      <button type="button" onClick={controls.start}>
        Start
      </button>
      <button type="button" onClick={controls.stop}>
        Pause
      </button>
      <button type="button" onClick={controls.restart}>
        Restart
      </button>
    </section>
  );
}

Parameters

duration: number is required and should be positive. The optional settings are:

Property	Type	Default	Meaning
`easing`	`(progress: number) => number`	`Easing.linear`	Maps directional progress.
`autoStart`	`boolean`	`true`	Starts in the running state on mount.
`loop`	`boolean`	`false`	Begins another pass at each end.
`alternate`	`boolean`	`false`	Flips direction between loop passes.
`delay`	`number`	`0`	Delay before the first pass only.
`onEnd`	`() => void`	`undefined`	Latest callback, invoked after each completed pass.

These option and control types, plus the easing function, state, and direction types, are public type exports from rooks.

Return value

The hook returns [progress, controls]. progress is the easing output. Controls contain start, stop, reset, restart, state ("idle" | "running"), direction ("forward" | "backward"), and endCount.

Behavior and lifecycle

stop stores raw progress and start resumes from it. reset returns to progress 0, forward direction, and zero completions. restart resets, then starts through a zero-delay timer. A backward alternating pass ends at progress 0. Delay applies only to the first run after reset.

The latest easing options and onEnd callback are used by the frame callback, but changing most options does not reset an in-flight clock. autoStart is mount-only. Frames stop when state becomes idle and are cancelled on unmount. The zero-delay timer created by restart is not explicitly cancelled, so do not call it during teardown. A custom easing output is not clamped, and errors from easing or onEnd propagate from the frame callback.

Compatibility and accessibility

Server output uses the initial progress and state; motion begins after hydration. Honor reduced-motion preferences, avoid rapid flashing, and provide text or native semantics for information otherwise conveyed only by animation.