Orbit UIv1.5.0
Installation
Theme
Mode

Data display

Timeline

A vertical record of what happened and when — activity feeds, task history, audit trails. Each event reads as one sentence (who · did what · to what), with a colour-coded marker on a continuous rail. Four density variants, six event types, and optional day grouping.

$npx shadcn@latest add @orbit/timeline

Overview

The grouped variant inside an activity card: icon tiles on a 2px rail, with mono day headers splitting the stream.

ActivityOrbit
Grouped by day
Today
  1. Jordan Lee completed ORB-1377
  2. Priya Nair commented on ORB-1402
    “The empty state copy reads great — let’s ship it and revisit the illustration next sprint.”
  3. Alex Rivera moved ORB-1390 → In review
Yesterday
  1. Sam Chen created ORB-1428
    Ship onboarding flow — audit current steps, draft v2.
  2. Sam Chen assigned ORB-1410 to Priya
  3. Mei Wong attached a file to ORB-1388

Anatomy

Every entry is the same three parts: a marker that encodes the event type (a quiet dot, or an icon tile with a glyph), a 2px rail that threads the markers into one continuous thread, and a one-line sentence — actor, action, target — with an avatar and timestamp beneath. Targets render in mono + brand colour when they’re IDs.

dot marker · rail · sentence with meta
  1. Sam Chen created ORB-1428
    Ship onboarding flow — audit current steps, draft v2.
  2. Sam Chen assigned ORB-1410 to Priya
  3. Mei Wong attached a file to ORB-1388

Variants

From a quiet dot-and-line feed to icon tiles with day headers — pick the weight the surface needs. The variant prop switches between them; non-grouped variants flatten day groups onto one unbroken rail.

defaultdots
  1. Jordan Lee completed ORB-1377
  2. Priya Nair commented on ORB-1402
    “The empty state copy reads great — let’s ship it and revisit the illustration next sprint.”
  3. Alex Rivera moved ORB-1390 → In review
  4. Sam Chen created ORB-1428
    Ship onboarding flow — audit current steps, draft v2.
  5. Sam Chen assigned ORB-1410 to Priya
  6. Mei Wong attached a file to ORB-1388
iconicon tiles
  1. Jordan Lee completed ORB-1377
  2. Priya Nair commented on ORB-1402
    “The empty state copy reads great — let’s ship it and revisit the illustration next sprint.”
  3. Alex Rivera moved ORB-1390 → In review
  4. Sam Chen created ORB-1428
    Ship onboarding flow — audit current steps, draft v2.
  5. Sam Chen assigned ORB-1410 to Priya
  6. Mei Wong attached a file to ORB-1388
compactdense, one-line
  1. Jordan Lee completed ORB-1377
  2. Priya Nair commented on ORB-1402
  3. Alex Rivera moved ORB-1390 → In review
  4. Sam Chen created ORB-1428
  5. Sam Chen assigned ORB-1410 to Priya
  6. Mei Wong attached a file to ORB-1388
groupedday headers
Today
  1. Jordan Lee completed ORB-1377
  2. Priya Nair commented on ORB-1402
    “The empty state copy reads great — let’s ship it and revisit the illustration next sprint.”
  3. Alex Rivera moved ORB-1390 → In review
Yesterday
  1. Sam Chen created ORB-1428
    Ship onboarding flow — audit current steps, draft v2.
  2. Sam Chen assigned ORB-1410 to Priya
  3. Mei Wong attached a file to ORB-1388

Event types

Each event type carries a fixed tone pair (marker colour + soft tile tint) and a distinct glyph, so a reader learns the vocabulary once and then scans by colour. Pass a custom icon to extend the set.

createdNew task, project or item createdvar(--pri)
completedAn item marked done or closedvar(--success)
commentA reply or note added to an itemvar(--ink-soft)
statusA state or column changevar(--warning)
assignedOwnership handed to a personvar(--acc)
attachmentA file or link attachedpri/danger mix

Props

PropTypeDefaultDescription
variant"default" | "icon" | "compact" | "grouped""default"Density / treatment: 11px dots, 30px icon tiles, 8px dots one-line, or icon tiles with day headers.
itemsTimelineItem[]—Flat event list for non-grouped feeds.
groupsTimelineGroup[]—Day-grouped events: { label, items }. Non-grouped variants flatten them onto one rail.
item.type"created" | "completed" | "comment" | "status" | "assigned" | "attachment"—Picks the marker's tone pair and glyph. Omit for a neutral brand dot.
item.actor / verb / targetstring—The sentence parts — bold actor, plain verb, emphasized target. Or pass title for a fully custom line.
item.targetMonobooleanfalseRender the target in mono + brand colour (IDs like ORB-1428).
item.descriptionReactNode—Secondary line under the sentence. Hidden in the compact variant.
item.contentReactNode—Free-form slot after the description — cards, previews, attachments.
item.time / datetimestring—Human-readable timestamp, plus an optional machine-readable value for the <time> element.
item.avatar{ initials, color? }—18px initials chip next to the time.
item.iconReactNode—Custom 14px glyph for icon-tile variants, drawn with currentColor.
…restHTMLAttributes—Everything else is forwarded to the root element, including ref.

Usage

Do

Lead with the actor

“Sam moved ORB-1390” scans faster than a passive “ORB-1390 was moved”. People anchor on who.

Don’t

Mix unrelated streams

A feed of everything everywhere becomes noise. Scope it to one project, person, or item.

Do

Group long feeds by day

Day headers give a wall of events a scannable spine and let the rail breathe between sessions.

Don’t

Rely on colour alone

Each marker pairs a colour with a distinct glyph and a text verb, so meaning survives without hue.

Keyboard & accessibility

The timeline is presentational, not interactive — semantics do the work.

listEvents render as a semantic <ol>, so screen readers announce position and count.
textEvery event is a full sentence — meaning never depends on the marker colour.
timePass datetime to get a real <time> element behind the human-readable label.
tonesMarker colours are token pairs, so they hold up across dark mode and all presets.