# tween

`tween(options)` returns an immutable
[`PibblAnimationDefinition`](/reference/types/canvas-runtime/#pibblanimationdefinition).
Numbers interpolate linearly by default; other value types require an explicit
interpolator. `from` may be omitted so playback captures the output's activation
value.

Use [`drive`](/reference/functions/drive/) to bind the definition to a writable signal.

Related types: [`PibblTweenOptions`](/reference/types/canvas-runtime/#pibbltweenoptions)
and [`PibblInterpolator`](/reference/types/canvas-runtime/#pibblinterpolator).

## API details from source

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

Returns an opaque immutable tween definition.

```ts
tween: <T = number>(options: Readonly<PibblTweenOptions<T>>) => PibblAnimationDefinition<T>
```

Related API: [tween](/reference/functions/tween/), [PibblTweenOptions](/reference/types/canvas-runtime/#pibbltweenoptions), [PibblAnimationDefinition](/reference/types/canvas-runtime/#pibblanimationdefinition).

### Parameters

- **`options`** — Start and end values, duration, easing, and interpolation settings. See
[PibblTweenOptions](/reference/types/canvas-runtime/#pibbltweenoptions) .

### Returns

An immutable tween definition. See [PibblAnimationDefinition](/reference/types/canvas-runtime/#pibblanimationdefinition).

### See also

[PibblTweenOptions](/reference/types/canvas-runtime/#pibbltweenoptions)

[PibblAnimationDefinition](/reference/types/canvas-runtime/#pibblanimationdefinition)

[View source — packages/core/src/lib/animation/definition.ts:553](/source/packages/core/src/lib/animation/definition-ts/#L553)

## 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

- [Tween playback controls](/minimal-examples/animation/tween/): Animate a signal and control the mounted playback with native buttons. [Plain source](/minimal/animation/tween.tsx)
## Documentation version

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