useAnimatedValue

Read as Markdown

useAnimatedValue(target, { animation, initial?, equals?, debugName? }) returns one stable readonly signal. Supply an immutable definition or a pure factory:

import { useAnimatedValue, spring, tween, easing } from "@pibbl/core";
function useMotion(targetX: number, targetOpacity: number) {
  const x = useAnimatedValue(targetX, {
    animation: spring({ stiffness: 180, damping: 12 }),
    initial: 0,
  });
  const opacity = useAnimatedValue(targetOpacity, {
    animation: tween({ duration: 200, easing: easing.easeOut }),
  });
  return { x, opacity };
}

The hook supplies the current and target endpoints to spring and tween definitions. Spring retargeting preserves committed analytic velocity; tween retargeting starts a full new duration. Reusable definitions are never mutated. For drive, spring and tween definitions still need an explicit to value.

Custom factories receive { from, to, velocity } and return a definition, such as defineAnimation({ duration, sample }). They run synchronously during render, may be evaluated more than once, and must not write signals or call hooks. Factory errors reject the render before target adoption. Other definitions such as keyframes keep their authored samples; use a factory when their samples need to depend on the target.

Omitting initial presents the mount target immediately. A different initial value animates after successful mount. Options and individual hook fields may be signals; use a computed definition to react to algorithm parameters.

Related types: Signal, PibblAnimatedValueOptions, and PibblAnimationTarget.

API details from source

Presents a target through an immutable animation definition or a pure animation factory.

useAnimatedValue: <T>(targetInput: SignalValue<T>, optionsInput: SignalValue<AnimatedValueInputs<NoInfer<T>>>) => Signal<T>

Related API: useAnimatedValue, SignalValue, Signal.

Parameters

• targetInput — Target value or signal. See SignalValue.

• optionsInput — Animation definition, initial value, equality, and diagnostic settings; fields and the options object may be signals. See PibblAnimatedValueOptions.

Returns

One stable readonly animated signal. See Signal.

View source — packages/core/src/lib/hooks/use-animated-value.ts:86

Implementation guidance for agents

Read the Animation and scheduling companion for ownership, adaptation, failure modes, and verification. Agent start provides the version-selection workflow.

Complete minimal examples

• Animate changing targets: Compare a tween and spring as the same target changes. Plain source

Interactive examples

• Signals and animation · Full page

Documentation version

Documentation built with @pibbl/core 0.0.2, revision 380919b. ALPHA — NOT FOR PRODUCTION USE.