Skip to content
Browse documentation

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.

Used forSleep trackingFocus sessionsWorkoutsStudio and streams

Install with the shadcn CLI

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

Registered the namespace? Then it’s shadcn add @hairline/stage-timeline. Set it up

Templates

Need the whole page?

61 Next.js landing pages, each designed from scratch. Try any of them live; one is $39, all of them $159, and 6 are free.

All 61 templates

Where it’s used

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

What it handles for you

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

Instead of wiring uphypnogramsleep stages chartsession timelineheart rate zones chartstepped line chart
  1. Stages over time

    Plateaus at each stretch’s height in its stage’s colour, joined by steps.

  2. A clock that reads

    The total at rest; the time under your finger while you scrub.

  3. Scrub anywhere

    Mouse, touch drag, or arrow keys from stretch to stretch.

  4. No tooltip

    The corner and the clock carry the reading, so nothing covers the chart.

  5. Your stages

    Any set of stages with their own labels and colours.

  6. Screen readers

    A slider whose value reads the time, stage and detail.

Overview

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.

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.

Usage

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 }]}/>

Works with

Last night from a sleep API

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

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

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= "Session"
string / ReactNode
Top left.
ticks
string[]
Times under the timeline; by default the first, middle and last.
tone= "midnight"
"cobalt" | "ember" | "rose" | "emerald" | "midnight" | "violet" | string
The lacquer’s colour.
accent= "#dcfc4e"
string
The cursor.

Accessibility and motion

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

Requirements

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

The CLI also installs Text morph.

Source

"use client";import * as React from "react";import { lacquer, type LacquerTone } from "./lacquer";import { TextMorph } from "./text-morph";import { EASE_OUT, useInteractionReducedMotion } from "./ui-interaction-motion";/* ───────────────────────────────────────────────────────── * STAGE TIMELINE: a session as stages over time * *   steps    each stretch of the session is a short plateau at *            its intensity, in its stage's colour, joined by a *            fine stepped line, with a bead on each *   clock    a dot-matrix readout shows how long the session *            ran; point into the timeline and its dots change *            over to the time under your finger, column by *            column, and back when you let go *   scrub    a lime cursor follows the pointer; the stretch under *            it thickens and its bead grows, and the corner names *            the time and the stage in that stage's colour * * An object with its own dark lacquer finish: the same on a light * page or a dark one. * * Reduced motion: dots and cursor change in place. * ───────────────────────────────────────────────────────── */export interface TimelineStage {  id: string;  label: string;  /** Any CSS colour. */  color: string;}export interface TimelinePoint {  /** Shown on the clock and in the corner: "22:25". */  time: string;  /** A stage id. */  stage: string;  /** How high the stretch sits, 0 to 100. */  value: number;  /** Read out with it: "−11 LUFS", "58 bpm". */  detail?: string;}export interface StageTimelineProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {  points: TimelinePoint[];  stages: TimelineStage[];  /** How long it ran, on the clock at rest: "3:48". Digits, ":" and "." */  total: string;  /** Beside the clock at rest: "h · 21:10 to 00:58". */  caption?: string;  title?: string;  icon?: React.ReactNode;  /** Times under the timeline; by default the first, middle and last. */  ticks?: string[];  /** The lacquer: a named tone or any CSS colour. */  tone?: LacquerTone | (string & {});  /** The cursor. */  accent?: string;}// 5 × 7 dot glyphs, one string per row.const GLYPHS: Record<string, string[]> = {  "0": ["01110", "10001", "10011", "10101", "11001", "10001", "01110"],  "1": ["00100", "01100", "00100", "00100", "00100", "00100", "01110"],  "2": ["01110", "10001", "00001", "00010", "00100", "01000", "11111"],  "3": ["11110", "00001", "00001", "01110", "00001", "00001", "11110"],  "4": ["10010", "10010", "10010", "11111", "00010", "00010", "00010"],  "5": ["11111", "10000", "11110", "00001", "00001", "10001", "01110"],  "6": ["00110", "01000", "10000", "11110", "10001", "10001", "01110"],  "7": ["11111", "00001", "00010", "00100", "01000", "01000", "01000"],  "8": ["01110", "10001", "10001", "01110", "10001", "10001", "01110"],  "9": ["01110", "10001", "10001", "01111", "00001", "00010", "01100"],  ":": ["00000", "00000", "00100", "00000", "00100", "00000", "00000"],  ".": ["00000", "00000", "00000", "00000", "00000", "00000", "00100"],  " ": ["00000", "00000", "00000", "00000", "00000", "00000", "00000"],};/** A dot-matrix readout of a fixed number of cells; a change lights and dims dots column by column, left to right. */function DotClock({ text, cells, reduced }: { text: string; cells: number; reduced: boolean }) {  const padded = text.padStart(cells, " ").slice(-cells);  return (    <span aria-hidden className="inline-flex items-center gap-[5px]">      {Array.from(padded).map((ch, c) => {        const rows = GLYPHS[ch] ?? GLYPHS[" "];        return (          <span key={c} className="grid grid-cols-[repeat(5,3px)] gap-[2px]">            {rows.flatMap((row, r) =>              Array.from(row).map((bit, x) => (                <span                  key={`${r}-${x}`}                  className="block size-[3px] rounded-full"                  style={{                    background: bit === "1" ? "rgb(255 255 255 / 0.96)" : "rgb(255 255 255 / 0.09)",                    transition: reduced ? "none" : `background-color 200ms ease-out ${(c * 5 + x) * 9}ms`,                  }}                />              )),            )}          </span>        );      })}    </span>  );}export function StageTimeline({  points,  stages,  total,  caption,  title = "Session",  icon,  ticks,  tone = "midnight",  accent = "#dcfc4e",  className = "",  style,  ...props}: StageTimelineProps) {  const reduced = useInteractionReducedMotion();  const gradient = React.useId();  const box = React.useRef<HTMLDivElement>(null);  const [width, setWidth] = React.useState(0);  const [index, setIndex] = React.useState(() => points.reduce((best, p, i) => (p.value > points[best].value ? i : best), 0));  const [cursor, setCursor] = React.useState<number | null>(null);  const [active, setActive] = React.useState(false);  const [dragging, setDragging] = React.useState(false);  const color = (id: string) => stages.find((s) => s.id === id)?.color ?? "#fff";  const stageOf = (id: string) => stages.find((s) => s.id === id)?.label ?? id;  React.useLayoutEffect(() => {    const el = box.current;    if (!el) return;    const measure = () => setWidth((w) => (w === el.offsetWidth ? w : el.offsetWidth));    measure();    const ro = new ResizeObserver(measure);    ro.observe(el);    return () => ro.disconnect();  }, []);  const H = 72;  const padX = 6;  const padY = 10;  const n = points.length;  const step = n ? (width - padX * 2) / n : 0;  const segs = points.map((p, i) => {    const x1 = padX + i * step + 3;    const x2 = padX + (i + 1) * step - 3;    return { x1, x2, cx: (x1 + x2) / 2, y: H - padY - (Math.max(0, Math.min(100, p.value)) / 100) * (H - padY * 2), p };  });  let path = "";  segs.forEach((s, i) => {    if (i === 0) path = `M ${s.x1.toFixed(1)} ${s.y.toFixed(1)} L ${s.x2.toFixed(1)} ${s.y.toFixed(1)}`;    else {      const prev = segs[i - 1];      const mid = ((prev.x2 + s.x1) / 2).toFixed(1);      path += ` L ${mid} ${prev.y.toFixed(1)} L ${mid} ${s.y.toFixed(1)} L ${s.x1.toFixed(1)} ${s.y.toFixed(1)} L ${s.x2.toFixed(1)} ${s.y.toFixed(1)}`;    }  });  const current = segs[index];  const point = points[index];  const cursorX = cursor ?? current?.cx ?? 0;  const cells = Math.max(total.length, ...points.map((p) => p.time.length));  const tickLabels = ticks ?? (n ? [points[0].time, points[Math.floor((n - 1) / 2)].time, points[n - 1].time] : []);  const fromPointer = (clientX: number) => {    const el = box.current;    if (!el || !n) return;    const r = el.getBoundingClientRect();    const x = Math.max(padX, Math.min(r.width - padX, clientX - r.left));    setCursor(x);    setIndex(Math.max(0, Math.min(n - 1, Math.floor((x - padX) / step))));  };  const live = active || dragging;  return (    <div className={`relative flex w-full flex-col overflow-clip rounded-[22px] px-5 py-4 select-none ${className}`} style={{ ...lacquer(tone), ...style }} {...props}>      <div className="flex items-center justify-between gap-2">        <div className="flex items-center gap-1.5 text-[11.5px] font-medium text-white/85">          {icon}          <span>{title}</span>        </div>        {point && (          <div className="font-mono text-[11.5px] font-medium tabular-nums transition-colors duration-300" style={{ color: color(point.stage) }}>            <TextMorph>{`${point.time} · ${stageOf(point.stage)}`}</TextMorph>          </div>        )}      </div>      <div className="mt-3 flex flex-wrap items-end gap-x-2.5 gap-y-1.5">        <DotClock text={live && point ? point.time : total} cells={cells} reduced={reduced} />        <span className="whitespace-nowrap pb-px text-[12px] tabular-nums text-white/70">          <TextMorph>{live && point ? `${stageOf(point.stage)}${point.detail ? ` · ${point.detail}` : ""}` : (caption ?? "")}</TextMorph>        </span>      </div>      <div className="mt-3">        <div          ref={box}          role="slider"          tabIndex={0}          aria-label={`${title} timeline`}          aria-valuemin={0}          aria-valuemax={Math.max(0, n - 1)}          aria-valuenow={index}          aria-valuetext={point ? `${point.time}, ${stageOf(point.stage)}${point.detail ? `, ${point.detail}` : ""}` : undefined}          onPointerEnter={(e) => e.pointerType === "mouse" && setActive(true)}          onPointerMove={(e) => (e.pointerType === "mouse" || dragging) && fromPointer(e.clientX)}          onPointerLeave={(e) => {            if (e.pointerType !== "mouse" || dragging) return;            setActive(false);            setCursor(null);          }}          onPointerDown={(e) => {            e.currentTarget.setPointerCapture(e.pointerId);            setDragging(true);            fromPointer(e.clientX);          }}          onPointerUp={() => {            setDragging(false);            setCursor(null);          }}          onPointerCancel={() => {            setDragging(false);            setCursor(null);          }}          onFocus={() => setActive(true)}          onBlur={() => setActive(false)}          onKeyDown={(e) => {            const to = { ArrowRight: index + 1, ArrowUp: index + 1, ArrowLeft: index - 1, ArrowDown: index - 1, Home: 0, End: n - 1 }[e.key];            if (to === undefined) return;            e.preventDefault();            setCursor(null);            setIndex(Math.max(0, Math.min(n - 1, to)));          }}          className="relative h-[72px] w-full cursor-ew-resize touch-none rounded-lg outline-none focus-visible:ring-1 focus-visible:ring-white/50"        >          {width > 0 && (            <svg aria-hidden width={width} height={H} viewBox={`0 0 ${width} ${H}`} className="absolute inset-0 overflow-visible">              <defs>                <linearGradient id={gradient} x1="0" y1="0" x2="0" y2="1">                  <stop offset="0%" stopColor={accent} stopOpacity="0.15" />                  <stop offset="50%" stopColor={accent} stopOpacity="0.95" />                  <stop offset="100%" stopColor={accent} stopOpacity="0.2" />                </linearGradient>              </defs>              <path d={path} fill="none" stroke="rgb(255 255 255 / 0.3)" strokeWidth="1.2" strokeLinejoin="round" />              {segs.map((s, i) => {                const on = i === index;                const c = color(s.p.stage);                return (                  <g key={`${s.p.time}-${i}`}>                    <line x1={s.x1} y1={s.y} x2={s.x2} y2={s.y} stroke={c} strokeWidth={on ? 2.6 : 1.7} strokeLinecap="round" opacity={on ? 1 : 0.7} style={{ transition: "stroke-width 200ms ease-out, opacity 200ms" }} />                    <circle cx={s.cx} cy={s.y} r={on ? 9 : 2.8} fill={c} opacity={on ? 0.24 : 0} style={{ transition: `r 260ms ${EASE_OUT}, opacity 200ms` }} />                    <circle cx={s.cx} cy={s.y} r={on ? 4.2 : 2.8} fill={c} opacity={on ? 1 : 0.88} style={{ transition: `r 260ms ${EASE_OUT}` }} />                  </g>                );              })}              <g style={{ transform: `translateX(${cursorX}px)`, transition: cursor === null && !reduced ? `transform 260ms ${EASE_OUT}` : "none" }}>                <line x1={0} y1={2} x2={0} y2={H - 2} stroke={`url(#${CSS.escape(gradient)})`} strokeWidth="1.5" />                <circle cx={0} cy={current?.y ?? 0} r={2.5} fill={accent} style={{ transition: reduced ? "none" : `cy 200ms ${EASE_OUT}` }} />              </g>            </svg>          )}        </div>        <div className="mt-1 flex items-center justify-between font-mono text-[10px] tabular-nums text-white/55">          {tickLabels.map((t, i) => (            <span key={`${t}-${i}`}>{t}</span>          ))}        </div>      </div>      <span className="sr-only">        {title}: {total}        {caption ? ` ${caption}` : ""}      </span>    </div>  );}

Registry item: /r/stage-timeline.json