# Stage timeline

> A session as stages over time on dark lacquer, with a dot-matrix clock that turns to the time under your finger as you scrub.

Sleep stages, a focus session, the zones of a workout: a session that moves through stages is usually a coloured bar nobody can read. Stage timeline draws each stretch as a short plateau at its height, in its stage’s colour, joined by a fine stepped line with a bead on each. A dot-matrix clock says how long the session ran. Point into the timeline and a lime cursor follows you, the stretch under it thickens and its bead grows, the corner names the time and the stage in that stage’s colour, and the clock’s dots change over to the time under your finger, column by column, then back to the total when you let go. It is an object with its own dark finish, the same on a light page or a dark one.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/stage-timeline.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: none
- Hairline UI components it needs (the CLI installs them too): `text-morph`
- Docs and live preview: https://hairlineui.com/ui/stage-timeline
- Registry item (source): https://hairlineui.com/r/stage-timeline.json

## Usage

```tsx
import { StageTimeline } from "@/components/stage-timeline";

<StageTimeline
  title="Last night"
  total="7:48"
  caption="h asleep"
  stages={[{ id: "deep", label: "Deep", color: "#5eead4" }, { id: "rem", label: "REM", color: "#fde047" }]}
  points={[{ time: "00:15", stage: "deep", value: 18 }, { time: "01:40", stage: "rem", value: 76 }]}
/>
```

## Last night from a sleep API

Map each stretch the tracker returns to a point; the height is whatever reads best for your stages.

```tsx
"use client";
import { StageTimeline } from "@/components/stage-timeline";

const HEIGHT = { awake: 92, rem: 76, light: 52, deep: 20 } as const;

export function LastNight({ night }: { night: { start: string; stage: keyof typeof HEIGHT; bpm: number }[]; asleep: string }) {
  return (
    <StageTimeline
      title="Last night"
      total={night.asleep}
      caption="h asleep"
      stages={[
        { id: "awake", label: "Awake", color: "#fb7185" },
        { id: "rem", label: "REM", color: "#fde047" },
        { id: "light", label: "Light", color: "#93c5fd" },
        { id: "deep", label: "Deep", color: "#5eead4" },
      ]}
      points={night.map((s) => ({ time: s.start, stage: s.stage, value: HEIGHT[s.stage], detail: `${s.bpm} bpm` }))}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `points` | `{ time: string; stage: string; value: number; detail?: string }[]` | – | The stretches in order: when each starts, its stage id, its height (0 to 100) and a detail to read out. |
| `stages` | `{ id: string; label: string; color: string }[]` | – | Your stages, with their colours. |
| `total` | `string` | – | On the clock at rest: "3:48". Digits, ":" and ".". |
| `caption` | `string` | – | Beside the clock at rest. |
| `title / icon` | `string / ReactNode` | `"Session"` | Top left. |
| `ticks` | `string[]` | – | Times under the timeline; by default the first, middle and last. |
| `tone` | `"cobalt" \| "ember" \| "rose" \| "emerald" \| "midnight" \| "violet" \| string` | `"midnight"` | The lacquer’s colour. |
| `accent` | `string` | `"#dcfc4e"` | The cursor. |

## States

- **rest**: The clock shows the total and the caption sits beside it; the busiest stretch is marked.
- **scrub**: The cursor follows the pointer; the stretch under it thickens to 2.6px and its bead grows to 4.2px over a soft disc (260ms). The corner and the caption morph; the clock’s dots change over in 200ms each, 9ms apart from the left.
- **let go**: The cursor settles on the middle of its stretch (260ms) and the clock turns back to the total.
- **reduced motion**: Dots and cursor change in place.

## What it handles

A stacked stage bar hides when each stage happened, and a hover tooltip covers the thing you’re reading.

- **Stages over time**: Plateaus at each stretch’s height in its stage’s colour, joined by steps.
- **A clock that reads**: The total at rest; the time under your finger while you scrub.
- **Scrub anywhere**: Mouse, touch drag, or arrow keys from stretch to stretch.
- **No tooltip**: The corner and the clock carry the reading, so nothing covers the chart.
- **Your stages**: Any set of stages with their own labels and colours.
- **Screen readers**: A slider whose value reads the time, stage and detail.

## Replaces

hypnogram, sleep stages chart, session timeline, heart rate zones chart, stepped line chart

## Where it fits

- **Sleep tracking**: Awake, REM, light and deep across a night, with heart rate per stretch.
- **Focus sessions**: Rest, flow and deep work across an evening.
- **Workouts**: Heart-rate zones across a run or a ride.
- **Studio and streams**: Loudness or energy stages across a set or a broadcast.

## Notes

- Always dark: the lacquer is the card’s own finish, so it reads the same on any page and needs no light version.
- The chart is drawn at its measured width (no stretched viewBox), so lines stay 1.2px and beads stay round at any size.
- The clock is 5 × 7 dots per character, all digits, ":" and "."; it pads to a fixed width so the readout never jumps. It’s hidden from screen readers, which read the slider’s value instead.
- Reduced motion changes the dots and the cursor in place.

License: MIT (https://hairlineui.com/license#components)
