Getting Started

Motion Cues provides threshold-based event detection for Motion MotionValue animations.

Subscribe once. Get onEnter / onExit callbacks when a value crosses named thresholds. Zero per-frame overhead after setup.

Install

npm install motion-cues

motion ^12.0.0 required. React ^19.0.0 optional (for /react).

Quick Start

import { defineCue, observeCue } from 'motion-cues';
import { useMotionValue } from 'motion/react';

const FLOOD = defineCue("flood", { half: 0.5, full: 1 });
const progress = useMotionValue(0);

const stop = observeCue(progress, FLOOD, {
  onEnter: (key) => console.log(`entered ${key}`),
  onExit: (key) => console.log(`exited ${key}`),
});

stop(); // cleanup

React

import { useCueState } from 'motion-cues/react';

function Progress() {
  const progress = useMotionValue(0);
  const flags = useCueState(progress, FLOOD);
  return <>{flags.half && <span>halfway</span>}</>;
}

Concurrent-safe (useSyncExternalStore), no useEffect, re-renders only on flips.

Why

progress.on("change", (v) => {
  if (v > 0.5 && !wasHalf) { /* entered half */ }
  if (v < 0.5 && wasHalf)   { /* exited half */ }
  wasHalf = v > 0.5;
});

One threshold, fine. Three thresholds plus bidirectional travel? You’re managing sorted arrays, direction flags, deduplication, cleanup — every time.

motion-cues does all of that for you.