# useAnimatedValue

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

```tsx
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`](/reference/types/canvas-runtime/#signal),
[`PibblAnimatedValueOptions`](/reference/types/canvas-runtime/#pibblanimatedvalueoptions),
and [`PibblAnimationTarget`](/reference/types/canvas-runtime/#pibblanimationtarget).

## API details from source

<span id="api-useAnimatedValue"></span>

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

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

Related API: [useAnimatedValue](/reference/hooks/use-animated-value/), [SignalValue](/reference/types/signal-inputs/#signalvalue), [Signal](/reference/types/canvas-runtime/#signal).

### Parameters

- **`targetInput`** — Target value or signal. See [SignalValue](/reference/types/signal-inputs/#signalvalue).

- **`optionsInput`** — Animation definition, initial value, equality, and diagnostic settings;
fields and the options object may be signals. See [PibblAnimatedValueOptions](/reference/types/canvas-runtime/#pibblanimatedvalueoptions).

### Returns

One stable readonly animated signal. See [Signal](/reference/types/canvas-runtime/#signal).

[View source — packages/core/src/lib/hooks/use-animated-value.ts:86](/source/packages/core/src/lib/hooks/use-animated-value-ts/#L86)

## Implementation guidance for agents

Read the [Animation and scheduling companion](/agents/topics/animation/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Animate changing targets](/minimal-examples/animation/targets/): Compare a tween and spring as the same target changes. [Plain source](/minimal/animation/targets.tsx)
## Interactive examples

- [Signals and animation](/examples/signals-and-animation/) · [Full page](/experience/signals-and-animation/)
## Documentation version

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