# drive

`drive(output, definition)` returns an immutable
[`PibblAnimationProgram`](/reference/types/canvas-runtime/#pibblanimationprogram). An accepted
run leases the writable output for its entire lifetime, including surrounding
waits. Competing writers fail unless playback requests replacement explicitly.

Creating this program does not update the signal or start playback. Pass it to
`usePlayback`, then call `play()` to run it. The signal is the destination, not
an observed input.

```ts
import { drive, tween, usePlayback, useSignal } from "@pibbl/core";

// Call inside a Pibbl component; invoke the returned function from an event handler.
function useMovement() {
  const x = useSignal(0);
  const movement = drive(x, tween({ from: 0, to: 100, duration: 300 }));
  const playback = usePlayback(movement);
  return { x, start: () => playback.play() };
}
```

`drive` replaces the former `track` name; there is no compatibility alias.

Related types: [`PibblAnimationDefinition`](/reference/types/canvas-runtime/#pibblanimationdefinition),
[`PibblAnimationProgram`](/reference/types/canvas-runtime/#pibblanimationprogram), and
[`WritableSignal`](/reference/types/canvas-runtime/#writablesignal).

## API details from source

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

Binds one animation definition to one writable signal.

```ts
drive: <T>(output: WritableSignal<T>, definition: PibblAnimationDefinition<T>) => PibblAnimationProgram
```

Related API: [drive](/reference/functions/drive/), [WritableSignal](/reference/types/canvas-runtime/#writablesignal), [PibblAnimationDefinition](/reference/types/canvas-runtime/#pibblanimationdefinition), [PibblAnimationProgram](/reference/types/canvas-runtime/#pibblanimationprogram).

### Parameters

- **`output`** — Writable signal that receives sampled values. See [WritableSignal](/reference/types/canvas-runtime/#writablesignal).

- **`definition`** — Animation definition to sample into the signal. See
[PibblAnimationDefinition](/reference/types/canvas-runtime/#pibblanimationdefinition) .

### Returns

A program that animates the supplied output signal. See [PibblAnimationProgram](/reference/types/canvas-runtime/#pibblanimationprogram).

### See also

[WritableSignal](/reference/types/canvas-runtime/#writablesignal)

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

[PibblAnimationProgram](/reference/types/canvas-runtime/#pibblanimationprogram)

[View source — packages/core/src/lib/animation/program.ts:780](/source/packages/core/src/lib/animation/program-ts/#L780)

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