timeline

Full documentation content.

<page path="/getting-started/0-introduction" title="Introduction"><![CDATA[URL: https://pmndrs.github.io/timeline/getting-started/0-introduction
Description: Write composable 3D behaviors like a story.

# Introduction

Write composable 3D behaviors like a story.

```bash
pnpm add three @react-three/fiber @react-three/timeline
```

### What does it look like?

| A simple timeline with 2 actions (look at red pill and look at blue pill) with an infinite loop | ![render of the above code](https://github.com/pmndrs/timeline/raw/main/docs/getting-started/basic-example.gif) |
| ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |

```tsx
const camera = useThree((s) => s.camera)
const redPill = useRef<Mesh>(null)
const bluePill = useRef<Mesh>(null)

useRunTimeline(function* () {
  while (true) {
    //transition to look at the red pill
    yield* action({ update: lookAt(camera, redPill.current!, spring()) })
    //transition to look at the blue pill
    yield* action({ update: lookAt(camera, bluePill.current!, spring()) })
  }
}, [])

return (
  <>
    <Text position-y={1} scale={0.3}>
      Remember: all I'm offering is the truth. Nothing more.
    </Text>
    <mesh position-y={-1} position-x={-2} rotation-y={(-30 / 180) * Math.PI} scale={0.2} scale-z={0.4} ref={redPill}>
      <sphereGeometry />
      <meshPhysicalMaterial emissive="red" emissiveIntensity={0.5} color="red" />
    </mesh>
    <mesh position-y={-1} position-x={2} rotation-y={(20 / 180) * Math.PI} scale={0.2} scale-z={0.4} ref={bluePill}>
      <sphereGeometry />
      <meshPhysicalMaterial emissive="blue" emissiveIntensity={5} color="blue" />
    </mesh>
  </>
)
```

## Documentation

- [What is a timeline?](./1-what-is-a-timeline.mdx)
- [Building your First Timeline](./2-first-timeline.mdx)
- [Overview of All Functions](./3-overview.mdx)
- [Tutorial: Building Complex Timelines using Parallel](../tutorials/5-parallel.mdx)
- [Tutorial: Building Graph Timelines](../tutorials/6-graph.mdx)
- [Tutorial: Use pmndrs/timeline in vanilla three.js](../tutorials/7-vanilla.mdx)

## Sponsors

This project is supported by a few companies and individuals building cutting edge 3D Web & XR experiences. Check them out!

![Sponsors Overview](https://bbohlender.github.io/sponsors/screenshot.png)

## Roadmap

\[ ] record, useRecordedTimeline, ... => allows to bind the timeline progress to any controls (e.g. scrolling); allowing using markers to attach scroll positions (e.g. button center screen) to the time of the timeline\
\[ ] yield\* cleanup(() => ...)\
\[ ] add external methods for the graph (set/get state externally)\
\[ ] queue with optional priority sorting and cancellation (configure what happens with the current timeline when canceled)\
\[ ] timeline visualization and `yield* marker(...)` to appear in the visualization (e.g. log values or complete json objects)
]]></page>
<page path="/getting-started/1-what-is-a-timeline" title="What is a Timeline?"><![CDATA[URL: https://pmndrs.github.io/timeline/getting-started/1-what-is-a-timeline
Description: Learn the core concepts—actions, updates, until, orchestration, and parallelism.

# What is a Timeline?

Learn the core concepts—actions, updates, until, orchestration, and parallelism.

Timelines let you write 3D behaviors like a story using generator functions (`function*`). You yield actions, wait for conditions, and compose sequences, loops, and parallel flows in a readable way.

At a high level, timelines are composed of actions and sub‑timelines. You chain them sequentially or run them in parallel to build rich behaviors.

### Actions

An action is a unit of work you `yield*` from a timeline. It can:

- provide a synchronous `init` function that runs when the action starts. Return a cleanup function to run when the action ends or is canceled. For async setup, wait for it first and keep the result: `yield* action({ until: load().then((value) => (model = value)) })`.
- provide an `update(state, clock)` called every frame; return `false` to finish
- provide an `until` condition or promise to decide when it finishes
- or any combination of the above

Use an action when you want to perform work over time, wait for something to happen, or both.

#### What does an action look like?

```ts
yield *
  action({
    update: (state, clock) => {
      // apply changes every frame
      return false // finish immediately
    },
  })
```

#### Waiting with `until`

```ts
yield * action({ until: timePassed(1, 'seconds') })
```

`until` accepts either

- a synchronous condition `(state, clock, actionTime) => boolean`, checked at the start of every frame (`timePassed`, `forever` and `queue.waitUntilNotEmpty()` return one), or
- a promise for external events (`mediaFinished`, `animationFinished`, a click, a network request).

Timelines only advance inside the per-frame `update` call, so everything is stepped by frames and simulation time: `timePassed` counts the sum of frame deltas, not wall clock time. A promise is noticed on the next frame after it resolves (at most one frame of latency), so prefer conditions for sequencing that happens inside your simulation and promises for events from the outside world.

> \[!IMPORTANT] Timelines are synchronous generators, so `await` is not available inside them. Wrap waits in an action and `yield*` it:
>
> ```ts
> yield* action({ until: someAsyncThing() })
> ```

#### How long does an action run?

An action runs until either:

- its `update` returns `false`, or
- its `until` condition is met or its `until` promise resolved.

If both are provided, the action keeps updating until the `until` is met.

When an action finishes, the timeline immediately continues to its next action within the same frame. The next action receives its first update in that same frame only if the finished action did not use it (its `until` was already met at the start of the frame); otherwise it starts updating on the next frame. Three actions whose `update` returns `false` therefore run on three consecutive frames.

#### The action clock

The `clock` passed to `update(state, clock, actionTime, memo)` contains:

- `delta`: seconds since the last frame, as passed to the update function returned by `runTimeline`
- `prevDelta`: the previous `delta`, `0` on the first frame (used by `spring`/`velocity` to infer velocity)
- `frame`: index of the current update, starting at 0 (lets a finished `transition`/`lookAt`/`offset*` hand its motion to the next action on the same target in the following frame)

The third argument, `actionTime`, is the time since the current action started (it resets between actions).

### Timelines

A timeline is a generator that yields actions (and can yield other timelines). You can loop, wait, and branch—writing behavior like a story.

#### Reusable timelines

A reusable timeline is a function that returns a timeline so it can be started many times.

```ts
function* reusableFadeIn() {
  yield* action({ until: timePassed(0.5, 'seconds') })
}

// later inside another timeline
yield * reusableFadeIn()
```

### Running timelines

- **React**: use `useRunTimeline(reusableTimeline, deps)`; it wires into `useFrame` and restarts on `deps` change.
- **Vanilla**: use `runTimeline(reusableTimeline)` to get an update function you call each frame with `deltaSeconds`.

```ts
// React
useRunTimeline(() => reusableFadeIn(), [someDep])

// Vanilla
const update = runTimeline(reusableFadeIn)
// in your render loop
update(state, deltaSeconds)
```

### Orchestration

You can chain actions/timelines sequentially or run them concurrently.

#### Sequential chaining

- **Sequential**: `yield* action(A); yield* action(B);` runs A, then B.

```ts
// Sequential
yield * action(A)
yield * action(B)
```

#### Parallel composition

- **All**: `yield* parallel('all', A, B)` continues when both finish and returns `false` if one of them returned `false`, otherwise `true`
- **Race**: `yield* parallel('race', A, B)` continues when the first finishes and returns what that one returned

```ts
const bothSucceeded = yield * parallel('all', A, B)
const firstOutcome = yield * parallel('race', A, B)
```

### Sub-timelines

Timelines compose: you can `yield*` another reusable timeline anywhere. This keeps complex behaviors modular and readable.

```ts
// Reusable timeline
function* someReusableTimeline() {
  yield* action({ until: timePassed(0.5, 'seconds') })
}

// Compose inside another timeline
yield * someReusableTimeline()
```

### Resources and cancellation

When a timeline is canceled (a race is lost, a graph state is left, the abort signal passed to `runTimeline` aborts), its `finally` blocks run synchronously. Use `try`/`finally` to bind a resource to a timeline's lifetime:

```ts
function* withSound() {
  const audio = new Audio('./sound.mp3')
  try {
    yield* action({ until: audio.play() })
    yield* action({ until: mediaFinished(audio) })
  } finally {
    audio.pause()
  }
}
```

### Graph timelines

Model behaviors as named states and transitions. `graph(initial, stateMap)` drives the flow; `<Graph>` and `<GraphState>` are the React components.

```ts
yield* graph('Idle', {
  Idle: {
    timeline: () => action({ update: ... }),
    transitionTo: { Run: { whenUpdate: timePassed(1, 'seconds') } }
  },
  Run: {/* ... */},
})
```

### QueueTimeline

Use a queue to sequence reusable timelines that are added dynamically. The queue drains in order until empty each time you run it.

```ts
const queue = new QueueTimeline()

// Manager timeline: repeatedly drain the queue, then wait for new work
function* queueManager() {
  while (true) {
    // runs each enqueued timeline sequentially until the queue is empty
    yield* queue.run()
    // pause until someone enqueues again
    yield* action({ until: queue.waitUntilNotEmpty() })
  }
}

// Somewhere else: enqueue work
queue.attach(function* () {
  yield* action({ until: timePassed(0.5, 'seconds') })
})

// Insert at a specific position (e.g. front of the queue)
queue.attach(function* () {
  /* ... */
}, 0)

// Clear pending items
queue.clear()
```

- **attach(timeline, index?)**: enqueue at optional index (default appends).
- **run()**: timeline that runs each enqueued timeline in FIFO order until empty (throws when run concurrently).
- **waitUntilNotEmpty()**: `until` condition that is met while the queue has entries.
- **length**: current number of queued timelines.

This is useful for input-driven behaviors (clicks, network events) where you want actions to play back-to-back without interleaving.

### GraphTimeline (class API)

Beyond the `graph(initial, map)` helper, you can control a state machine via the `GraphTimeline` class—attach/unattach states at runtime, read the current state, or force transitions.

```ts
const machine = new GraphTimeline('Idle', {
  Idle: {
    timeline: () => action({ update: () => true }), // keep updating until a transition fires
    transitionTo: {
      Run: { whenUpdate: timePassed(1, 'seconds') },
    },
  },
  Run: {
    timeline: () => action({ until: timePassed(0.5, 'seconds') }),
    transitionTo: { finally: 'Idle' }, // jump here after timeline completes
  },
})

// Start the graph inside a timeline
yield* machine.run()

// At runtime, you can manipulate it:
machine.getState() // 'Idle'
machine.setState('Run') // cancels the current state; 'Run' starts on the next frame
machine.attach('Attack', () => action({ until: timePassed(0.2, 'seconds') }), { finally: 'Idle' })
machine.unattach('Attack')
```

Transitions can be expressed with:

- **whenUpdate(state, clock, actionTime) => boolean**: transition when this returns true; checked at the start of every frame with `actionTime` being the time the state ran before this frame, so the next state receives that frame (e.g. `timePassed(1, 'seconds')`)
- **whenPromise: () => Promise**: transition on the next frame after the promise resolved
- **finally: 'StateName'**: default next state after the state's `timeline` completes

A state's `timeline` may also return a state name to transition to:

```ts
function* Run() {
  // ... do work ...
  return 'Idle' // explicit next state
}
```

### Built‑ins for motion

- **Action updates**: `transition`, `lookAt`, `offsetDistance`, `offsetRotation`
- **Eases**: `spring(preset|config)`, `time(durationSec)`, `velocity(speed, maxAccel?)`
- **Helpers**: `worldSpace(type, object)`, `property(object, key)`, waits like `timePassed`, `mediaFinished`, `animationFinished`, plus `doUntil`/`doWhile`

Explore full, runnable examples in the tutorials:

- Building your First Timeline
- Building Complex Timelines using Parallel
- Building Graph Timelines
- Use pmndrs/timeline in vanilla three.js
]]></page>
<page path="/getting-started/2-first-timeline" title="Building your First Timeline."><![CDATA[URL: https://pmndrs.github.io/timeline/getting-started/2-first-timeline
Description: Step-by-step - create a React scene and orchestrate camera behavior with a timeline.

# Building your First Timeline.

Step-by-step - create a React scene and orchestrate camera behavior with a timeline.

This walks you through building the intro example from scratch.

### Final result

Interactive code example (available on the documentation website).

### Build it in steps

1. Install

```bash
pnpm add three @react-three/fiber @react-three/drei @react-three/timeline
```

2. Minimal scene

Create `App.tsx` and render a scene with two meshes.

3. The scene shell

```tsx
// App.tsx
import { Canvas } from '@react-three/fiber'

export default function App() {
  return (
    <Canvas style={{ position: "absolute", inset: "0", touchAction: "none" }}>
      {/* Add <Scene /> in the next step */}
    </Canvas>
  )
}
```

4. Add meshes and references

```tsx
import { useRef } from 'react'
import { Mesh } from 'three'
import { Text } from '@react-three/drei'

function Scene() {
  const red = useRef<Mesh>(null)
  const blue = useRef<Mesh>(null)
  return (
    <>
      <Text color="black" position-y={1} scale={0.3}>Your first timeline</Text>
      <mesh ref={red} position-x={-2} position-y={-1} rotation-y={(-30/180)*Math.PI} scale={[0.2,0.2,0.4]}>
        <sphereGeometry />
        <meshPhysicalMaterial emissive="red" emissiveIntensity={1.5} color="red" />
      </mesh>
      <mesh ref={blue} position-x={2} position-y={-1} rotation-y={(20/180)*Math.PI} scale={[0.2,0.2,0.4]}>
        <sphereGeometry />
        <meshPhysicalMaterial emissive="blue" emissiveIntensity={5} color="blue" />
      </mesh>
    </>
  )
}
```

5. Add the timeline

We use `useTimeline` to run a `while (true)` loop, which keeps the sequence going, and each `yield* action({ update: lookAt(...) })` eases the camera toward a target using a spring; once the ease completes, the next action starts.

```tsx
import { useThree } from '@react-three/fiber'
import { useTimeline, action, lookAt, spring, springPresets } from '@react-three/timeline'

function Scene() {
  const camera = useThree((s) => s.camera)
  const red = useRef<Mesh>(null)
  const blue = useRef<Mesh>(null)

  useRunTimeline(function* () {
    while (true) {
      yield* action({ update: lookAt(camera, red.current!, spring(springPresets.stiff)) })
      yield* action({ update: lookAt(camera, blue.current!, spring(springPresets.stiff)) })
    }
  }, [])
  // ...return meshes as above
}
```

7. Mount the scene

```tsx
export default function App() {
  return (
    <Canvas style={{ position: "absolute", inset: "0", touchAction: "none" }}>
      <Scene />
    </Canvas>
  )
}
```
]]></page>
<page path="/getting-started/3-overview" title="Overview of All Functions."><![CDATA[URL: https://pmndrs.github.io/timeline/getting-started/3-overview
Description: Overview of function categories (action update, action until, action update ease)

# Overview of All Functions.

Overview of function categories (action update, action until, action update ease)

## Action Update Ease

### spring

action update ease function easing values according to spring physics

#### Parameters

- \`config\` (`{ damping: number; mass: number; maxVelocity?: number; stiffness: number }`): allows to configure the physical properties of the spring (available presets are `springPresets.gentle`, `springPresets.wobbly`, `springPresets.stiff`) - default is `springPresets.gentle`

#### Returns

`EaseFunction<unknown>`

### time

action update easing function for a linear ease based on the provided duration in seconds

#### Parameters

- \`duration\` (number)

#### Returns

`EaseFunction<unknown>`

### velocity

action update ease function for easing values according to the target velocity may overshoot the goal; finishing does not guarantee exact arrival at a waypoint

#### Parameters

- \`velocity\` (number)
- \`maxAcceleration\` (number): (optional) can be used to limit the change in velocity

#### Returns

`EaseFunction<unknown>`

## Action Update

### lookAt

action update function for making a src object or quaternion look from its position towards the `toPosition`

#### Parameters

- \`from\` (`Object3D<Object3DEventMap> | { position: Vector3 | () => Vector3; rotation: Quaternion | (newValue?: Quaternion) => Quaternion }`)
- \`toPosition\` (`Object3D<Object3DEventMap> | Vector3 | number[] | () => Vector3 | number[]`)
- \`ease\` (`EaseFunction<T>`): allows to ease the rotation from the current state to the target position

> \[!NOTE] World forward is −Z with up = `Object3D.DEFAULT_UP`. If source and target positions are identical.

#### Returns

`ActionUpdate<T>`

### offsetDistance

action update function for making a src object or position move away/towards the to position to be at the specified distance combined with offsetRotation, this action update describes an exact target position in orbital coordinates

#### Parameters

- \`from\` (`Object3D<Object3DEventMap> | Vector3 | (newValue?: Vector3) => Vector3`)
- \`to\` (`Object3D<Object3DEventMap> | Vector3 | () => Vector3`)
- \`distance\` (number)
- \`ease\` (`EaseFunction<T>`): allows to ease the position from the current state to the position with the target distance

> \[!NOTE] If `from` and `to` coincide (zero distance), direction is undefined; the action no‑ops and finishes.

#### Returns

`ActionUpdate<T>`

### offsetRotation

action update function for making a src object or position move to a position with the specified rotation offset combined with offsetDistance, this action update describes an exact target position in orbital coordinates

#### Parameters

- \`from\` (`Object3D<Object3DEventMap> | Vector3 | (newValue?: Vector3) => Vector3`)
- \`to\` (`Object3D<Object3DEventMap> | Vector3 | () => Vector3`)
- \`rotation\` (`Quaternion | Euler | number[] | () => Quaternion | Euler | number[]`): the offset rotation in world space

> \[!NOTE] Applies a world‑space rotation around `to` using a forward vector derived from the world up axis. Pair with `offsetDistance` to define orbital targets.

- \`ease\` (`EaseFunction<T>`): allows to ease the position from the current state to the position with the target rotation offset

#### Returns

`ActionUpdate<T>`

### transition

action update function for making a src object, position, rotation, scale, number change towards the to value

#### Parameters

- \`from\` (`TransitionFrom | (newValue?: Vector3 | Quaternion) => number | TransitionFrom`)
- \`to\` (`TransitionTo | () => TransitionTo`)
- \`ease\` (`EaseFunction<T>`): allows to ease the value from the current value to the target value Without an ease, vector and numeric cuts carry the preceding frame's velocity into the next action. An intervening idle frame clears that momentum; rotation cuts do not carry angular velocity.

#### Returns

`ActionUpdate<T>`

## Action Until

### animationFinished

action until function for executing an action until a animation has finished playing

#### Parameters

- \`animation\` (AnimationAction)

#### Returns

`Promise<void>`

### forever

action until condition for executing an action until forever

#### Returns

`UntilCondition<unknown>`

### mediaFinished

action until function for executing an action until a html media has finished playing

#### Parameters

- \`media\` (`HTMLAudioElement | HTMLVideoElement`)

#### Returns

`Promise<unknown>`

### promiseConcat

action until function for concatenating multiple action until functions

#### Parameters

- \`promises\` (`Promise<unknown>[]`)

#### Returns

`Promise<void>`

### timePassed

action until condition for executing an action until a certain amount of simulation time (the sum of frame deltas) has passed

#### Parameters

- \`time\` (number)
- \`unit\` (`"seconds" | "milliseconds"`)

#### Returns

`UntilCondition<unknown>`

## Structural

### abortable

a timeline wrapper that allows to make any timeline externally cancelable via an abort signal aborting cancels the wrapped timeline immediately; the wrapper finishes on the next frame without using it

#### Parameters

- \`timeline\` (`Timeline<T>`)
- \`abortSignal\` (AbortSignal)

#### Returns

`NonReuseableTimeline<T>`

### action

core function for yielding an action used via `yield* action({...})` allows to run this action `until` a certain event and execute an `update` function until the action is finished

#### Parameters

- \`params\` (`ActionParams<T>`)

#### Returns

`NonReuseableTimeline<T>`

### doUntil

function for generating a timeline that repeats the inner timeline until the `until` condition or promise is met

#### Parameters

- \`until\` (`Until<T>`)
- \`timeline\` (`ReusableTimeline<T>`)

#### Returns

`NonReuseableTimeline<T>`

### doWhile

function for generating a timeline that repeats the inner timeline while the condition holds the condition is checked at the start of every frame; once it fails, the frame passes on to what follows

#### Parameters

- \`condition\` (`UntilCondition<T>`)
- \`timeline\` (`ReusableTimeline<T>`)

#### Returns

`NonReuseableTimeline<T>`

### graph

timeline function for building a state graph with transitions as edges

#### Parameters

- \`enterStateName\` (string): is the name of the initial state
- \`stateMap\` (`GraphTimelineStateMap<T>`): is the map of states including their transitions to other states
- \`exitStateName\` (string)

#### Returns

`NonReuseableTimeline<T>`

### parallel

function for executing multiple timelines in parallel each timeline receives every frame in the given order; `false` and `true` entries are skipped without any timelines (e.g. all entries are `false`), it returns immediately

in a `"race"`, the first timeline that finishes ends the race before later timelines receive the frame; put conditions (e.g. `action({ until })`) first so that a met condition hands the frame on to what follows the race

the outcome (what `yield* parallel(...)` returns):

- `"race"` returns what the timeline that ended first returned (never what a cancelled timeline returns); `undefined` without timelines
- `"all"` returns `false` if any timeline returned `false`, otherwise `true` (a timeline returning nothing counts as succeeded); `true` without timelines

the race's outcome is typed from its timelines; with an explicit state type argument (`parallel<State>('race', ...)`) it is `unknown`

#### Parameters

- \`type\` (`"all" | "race"`): when to stop all timelines - either wait for `"all"` or cancel all timelines once the first timeline is done via `"race"`
- \`timelines\` (`(boolean | Timeline<T>)[]`)

#### Returns

`NonReuseableTimeline<T, RaceOutcome<B>>` for `"race"`, `NonReuseableTimeline<T, boolean>` for `"all"`

### runTimeline

function for starting a timeline starts the generator up to its first action immediately, then advances it inside the returned update function errors propagate to the caller; deltas are passed through without clamping or substeps

#### Parameters

- \`timeline\` (`Timeline<T, unknown>`)
- \`abortSignal\` (AbortSignal)

#### Returns

`Update<T>`

## Misc

### Action

attaches an action to the enclosing timeline; until is a factory evaluated when the action starts without dependencies, the latest props are read on the next start; changing dependencies reattaches the action

#### Parameters

- \`\_\_namedParameters\` (`{ dependencies?: unknown[]; until?: () => Until<RootState> } & Omit<ActionParams<RootState>, "until">`)

#### Returns

`null`

### property

helper function for building a write/read function of any property in an object reuse the same accessor across actions to preserve momentum; transition goals for numeric properties are plain numbers

#### Parameters

- \`object\` (`{ [Key in string]: number }`): the object from which to read/write a property
- \`key\` (K): the key of the property from which to read/write inside of the object

#### Returns

`(newValue?: Vector3 | Quaternion) => number`

### useRunTimeline

hook for running the specified timeline every frame errors thrown by the timeline propagate out of the frame callback

#### Parameters

- \`timeline\` (`ReusableTimeline<RootState, unknown>`)
- \`deps\` (`any[]`): tells the hook when to stop the previous timeline and restart the currently provided timeline

#### Returns

`void`

### worldSpace

helper function for building a write/read function of the position/euler/quaternion/scale for an object in world space useful when combined with other action update functions such as lookAt

#### Parameters

- \`type\` (Type)
- \`forObject\` (Object3D)
- \`offset\` (`number[]`)

#### Returns

`(newValue?: any) => WorldSpaceResults[Type]`
]]></page>
<page path="/getting-started/4-examples" title="Examples"><![CDATA[URL: https://pmndrs.github.io/timeline/getting-started/4-examples
Description: Examples made with react-three/timeline.

# Examples

Examples made with react-three/timeline.

- [![Screenshot from Showcase example](https://github.com/pmndrs/timeline/raw/main/docs/getting-started/lambo-thumbnail.jpeg)](https://react-three-timeline-lambo.vercel.app/)
]]></page>
<page path="/tutorials/5-parallel" title="Building Complex Timelines using Parallel"><![CDATA[URL: https://pmndrs.github.io/timeline/tutorials/5-parallel
Description: Run multiple timelines concurrently and wait for all or race the first.

# Building Complex Timelines using Parallel

Run multiple timelines concurrently and wait for all or race the first.

Use `parallel('all' | 'race', ...)` to orchestrate concurrent behaviors. In this example we move two cubes simultaneously and continue only when both finish.

> \[!NOTE] you can pass conditionally included timelines by using booleans; falsey entries are ignored. On `'race'`, non‑winning timelines are canceled and their cleanups run.

The following demo shows how the left cube constantly moves since it has to cover a larger distance while the right cube waits for the cube since both move at the same speed while the right cube has a shorter distance to travel.

Interactive code example (available on the documentation website).

### Key ideas

- **parallel('all', ...)** waits for all child timelines to finish. It returns `false` if a child returned `false`, otherwise `true`.
- **parallel('race', ...)** continues as soon as the first child finishes and cancels the rest. It returns what the first child returned.

### Build it in steps

1. Define a reusable `moveTo` sub-timeline (what it is): a small timeline that transitions a mesh position to a target using `transition(..., spring())`.

```tsx
export function* moveTo(ref: React.RefObject<Mesh>, to: Vector3) {
  if (!ref.current) return
  yield* action({ update: transition(ref.current.position, to, velocity(1, 5)) })
}
```

2. Create a `Scene` with two cubes and lights

```tsx
import { useRef } from 'react'
import { Mesh } from 'three'

function Scene() {
  const cubeA = useRef<Mesh>(null)
  const cubeB = useRef<Mesh>(null)
  return (
    <>
      <mesh ref={cubeA} position={[-2, 0, 0]}>
        <boxGeometry />
        <meshStandardMaterial color="hotpink" />
      </mesh>
      <mesh ref={cubeB} position={[2, 0, 0]}>
        <boxGeometry />
        <meshStandardMaterial color="orange" />
      </mesh>
      <ambientLight intensity={0.5} />
      <directionalLight position={[3, 3, 3]} intensity={1} />
    </>
  )
}
```

3. Add the timeline using `parallel('all')` then `parallel('race')`

```tsx
import { useTimeline, parallel } from '@react-three/timeline'
import { Vector3 } from 'three'

function Scene() {
  const cubeA = useRef<Mesh>(null)
  const cubeB = useRef<Mesh>(null)
  useRunTimeline(function* () {
    while (true) {
      yield* parallel('all', moveTo(cubeA, new Vector3(-3.5, 0.5, 0)), moveTo(cubeB, new Vector3(1.5, -0.5, 0)))
      yield* parallel('all', moveTo(cubeA, new Vector3(0, 0, 0)), moveTo(cubeB, new Vector3(0, 0, 0)))
    }
  }, [])
  // ...return cubes and lights from step 2
}
```

4. Mount the scene in a Canvas

```tsx
import { Canvas } from '@react-three/fiber'

export default function App() {
  return (
    <Canvas style={{ position: 'absolute', inset: '0', touchAction: 'none' }}>
      <Scene />
    </Canvas>
  )
}
```
]]></page>
<page path="/tutorials/6-graph" title="Building Graph Timelines"><![CDATA[URL: https://pmndrs.github.io/timeline/tutorials/6-graph
Description: Model behavior as states with transitions driven by time or conditions.

# Building Graph Timelines

Model behavior as states with transitions driven by time or conditions.

Graph timelines let you model states and transitions. We'll switch between two states (`red` and `blue`) depending on the mouse position, using promise-based triggers instead of React state.

In the following example, you can move the mouse to the left or right of the canvas to trigger a state transition.

Interactive code example (available on the documentation website).

### Key ideas

- Define a `stateMap` with `timeline` for each state and `transitionTo` conditions.
- Transitions can be driven by promises (e.g., “resolve when mouse is on the right side”).

Extras:

- You can return a state name from a state's `timeline` to jump programmatically.
- You can set `transitionTo: { finally: 'someState' }` to always transition after a state's timeline completes.

### Build it in steps

1. Create a reusable promise trigger for either side

```ts
function mouseOnSide(side: 'left' | 'right'): Promise<void> {
  return new Promise((resolve) => {
    function onMove(e: MouseEvent) {
      const onRight = e.clientX / window.innerWidth > 0.5
      if ((side === 'right' && onRight) || (side === 'left' && !onRight)) {
        window.removeEventListener('mousemove', onMove)
        resolve()
      }
    }
    window.addEventListener('mousemove', onMove)
  })
}
```

2. Start the graph with inline states (no separate variable) and render the scene. `graph` builds the state machine and `useRunTimeline` runs it.

```tsx
useRunTimeline(
  () =>
    graph('red', {
      red: {
        timeline: () => action({ update: lookAt(camera, red.current!, spring()) }),
        transitionTo: { blue: { whenPromise: () => mouseOnSide('right') } },
      },
      blue: {
        timeline: () => action({ update: lookAt(camera, blue.current!, spring()) }),
        transitionTo: { red: { whenPromise: () => mouseOnSide('left') } },
      },
    }),
  [camera],
)
```
]]></page>
<page path="/tutorials/7-vanilla" title="Use pmndrs/timeline in vanilla three.js"><![CDATA[URL: https://pmndrs.github.io/timeline/tutorials/7-vanilla
Description: Drive three.js scenes without React using @pmndrs/timeline.

# Use pmndrs/timeline in vanilla three.js

Drive three.js scenes without React using @pmndrs/timeline.

`@pmndrs/timeline` works in any three.js app — no React required. You create a timeline, start it, and call the returned update function each frame.

### Differences to React usage

- In React you use `useRunTimeline(...)` which ties into the render loop for you.
- In vanilla you call `runTimeline(timeline)` and invoke the returned function every frame with `deltaSeconds` (the library internally clamps large deltas to \~1/30s for stability).

## Build a scene with `@pmndrs/timeline`

Below is a complete example using two spheres and a camera that alternates between them.

Interactive code example (available on the documentation website).

The first step is to install the dependencies.

```bash
pnpm add three @pmndrs/timeline
```

Next, we create the `index.ts` file and import the necessary dependencies and setup a three.js scene.

1. Create a renderer, scene, and camera

```ts
const root = document.getElementById('root') as HTMLDivElement
const renderer = new WebGLRenderer()
renderer.outputColorSpace = SRGBColorSpace
renderer.toneMapping = ACESFilmicToneMapping
renderer.toneMappingExposure = 1
root.appendChild(renderer.domElement)

const scene = new Scene()
const camera = new PerspectiveCamera(80, 1, 0.1, 100)
camera.position.set(0, 0, 5)
scene.add(camera)
```

2. Optional: add postprocessing and lights

```ts
const composer = new EffectComposer(renderer, { frameBufferType: HalfFloatType })
composer.addPass(new RenderPass(scene, camera))
const bloom = new BloomEffect({ luminanceThreshold: 2, luminanceSmoothing: 0.9, height: 300 })
const vignette = new VignetteEffect({ eskil: false, offset: 0.1, darkness: 1.1 })
composer.addPass(new EffectPass(camera, bloom, vignette))
scene.add(new AmbientLight(0xffffff, 0.2))
```

3. Place meshes (targets for the camera)

```ts
const sphere = new SphereGeometry(1, 32, 32)
const redPill = new Mesh(sphere, new MeshPhysicalMaterial({ color: 'red', emissive: 'red', emissiveIntensity: 9 }))
redPill.position.set(-2, -1, 0)
redPill.scale.set(0.2, 0.2, 0.4)
redPill.rotation.y = (-30 / 180) * Math.PI
scene.add(redPill)

const bluePill = new Mesh(sphere, new MeshPhysicalMaterial({ color: 'blue', emissive: 'blue', emissiveIntensity: 30 }))
bluePill.position.set(2, -1, 0)
bluePill.scale.set(0.2, 0.2, 0.4)
bluePill.rotation.y = (20 / 180) * Math.PI
scene.add(bluePill)
```

4. Create and start the timeline

```ts
function* mainTimeline() {
  while (true) {
    yield* action({ update: lookAt(camera, redPill, spring(springPresets.stiff)) })
    yield* action({ until: timePassed(0.3, 'seconds') })
    yield* action({ update: lookAt(camera, bluePill, spring(springPresets.stiff)) })
    yield* action({ until: timePassed(0.3, 'seconds') })
  }
}
const update = runTimeline(mainTimeline())
```

5. Drive frames and handle resize

```ts
let last = performance.now()
function onFrame(now: number) {
  const delta = Math.max(1e-6, Math.min(1/30, Math.max(0, (now - last) / 1000)))
  last = now
  update(undefined, delta)
  composer.render(delta)
  requestAnimationFrame(onFrame)
}
requestAnimationFrame(onFrame)

function onResize() {
  const width = root.clientWidth
  const height = root.clientHeight
  camera.aspect = width / height
  camera.updateProjectionMatrix()
  renderer.setSize(width, height)
  renderer.setPixelRatio(window.devicePixelRatio)
  composer.setSize(width, height)
}
onResize()
window.addEventListener('resize', onResize)
```

6. Optional: add text and an HDRI environment

```ts
const font = await new FontLoader().loadAsync('https://threejs.org/examples/fonts/helvetiker_regular.typeface.json')
const textGeometry = new TextGeometry("Remember: all I'm offering is the truth. Nothing more.", { font, size: 0.3, depth: 0.02, curveSegments: 8 })
const text = new Mesh(textGeometry, new MeshStandardMaterial({ color: 0xcccccc, toneMapped: false }))
text.position.set(-4.5, 0.5, 0)
scene.add(text)

const hdr = await new RGBELoader().loadAsync('https://raw.githubusercontent.com/pmndrs/drei-assets/456060a26bbeb8fdf79326f224b6d99b8bcce736/hdri/studio_small_03_1k.hdr')
const pmrem = new PMREMGenerator(renderer)
pmrem.compileEquirectangularShader()
const env = pmrem.fromEquirectangular(hdr)
scene.environment = env.texture
scene.background = env.texture
scene.backgroundRotation.y = (90 / 180) * Math.PI
scene.backgroundBlurriness = 0.1
scene.backgroundIntensity = 0.1
hdr.dispose(); pmrem.dispose()
```

If you use vite (`pnpm add vite`), you can create a `index.html` file, add the following content, and run `pnpm vite`.

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document</title>
    <script type="module" src="index.ts"></script>
  </head>
  <body style="margin: 0;">
    <div id="root" style="position:absolute; inset: 0; touch-action: none"></div>
  </body>
</html>
```
]]></page>