Skip to main content

Timeline

Core

The GENERIC ordered-steps rail; an agent execution trace is AI/AgentTimeline and git history is Data/RevisionTimeline — see [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs).

import { Timeline } from "@elabs-ai/components-ui";
Install
npm install @elabs-ai/components-tokens @elabs-ai/components-ui

Skipping the @source line is the most common first failure: Tailwind does not scan node_modules, so every component renders unstyled. The one-time wiring

Prompt for your coding agent

Paste it into Claude Code, Cursor, Codex or any other coding agent. Text in [brackets] is yours to fill in.

Add the brand-ui Timeline component (from @elabs-ai/components-ui) to this project.

1. Read https://elabs-ai.com/llms.txt first: it maps every package and the rules. If you can use MCP servers, connect https://elabs-ai.com/mcp and use its search, docs and tokens tools. If not, run the same lookups in the terminal: `npx -y @elabs-ai/components-cli search "<what you need>"` and `npx -y @elabs-ai/components-cli docs <Component>`.
2. Look Timeline up before writing code: `npx -y @elabs-ai/components-cli docs Timeline` prints its real props, variants, what it pairs with and what to avoid.
3. If @elabs-ai/components-ui is not installed yet: `pnpm add @elabs-ai/components-tokens @elabs-ai/components-ui` (or `npm install @elabs-ai/components-tokens @elabs-ai/components-ui`). If this is the first brand-ui package in the project, wire it once: import `@elabs-ai/components-tokens/styles.css` plus the `themes/light.css` and `themes/dark.css` stylesheets in the CSS entry, add one Tailwind `@source` line per installed @elabs-ai package (Tailwind does not scan node_modules, so without it everything renders unstyled), and wrap the app root in `ThemeProvider` from `@elabs-ai/components-tokens`.
4. Use it here: [the screen or file, and what it should show]
5. Rules: use only @elabs-ai/components-* components and the semantic tokens — no raw colours, no raw font sizes, no arbitrary Tailwind values. Look up each component's real props with the docs tool before you use it; never guess a prop.
6. Done means: the typecheck passes, `npx -y @elabs-ai/components-cli audit src --strict` reports nothing, and you have opened the app and looked at every screen you touched in the light and the dark theme.

Examples

10 live examples

Compound

Tabular Timestamps

Canonical Statuses

Plain Chronology

`variant="plain"` is a CHRONOLOGY, not a process: neutral nodes, no status vocabulary, the one `current` item accented and `aria-current="step"`. The `label` slot carries the date (or a version) — in the label gutter beside the node from `@2xl`, above the title below that.

Horizontal

`orientation="horizontal"`: the same items side by side on one connector, nodes on top.

Responsive

`orientation="responsive"`: vertical below the root’s `@3xl` container width, horizontal from there — resize the canvas to see the same four items re-lay.

Labelled Status

The `label` gutter on the status rail — a release log: version beside the node, changes in `detail`.

Numbered Steps

`nodeSize="badge"`: a 32px disc that carries each item's `node` — the numbered “how it works” rail. Combine with `orientation="responsive"` for a row on a wide canvas and a column on a narrow one.

Badge Status

A `badge` node on the status rail: the disc takes the status fill and its content the matching ink.

API

Timeline

PropTypeDescription
itemsrequiredTimelineEntry[]

Also accepts: HTMLAttributes<HTMLOListElement>

TimelineItem

PropTypeDescription
statusStatusThe canonical execution status (closed 7-state enum, status-badge #189). Ignored by a `plain` root — use `current` there.
currentboolean`plain` variant only: this is the “now” step — accent node, `aria-current="step"`, and an sr-only “(current)” after the title.
labelReactNodeLeading meta (a date, a version) that sits in the label gutter beside the node at `@2xl`+ when vertical, and above the title otherwise.
nodeReactNodeContent for the node when the root is `nodeSize="badge"` — a step number, a glyph. Decorative (the disc is `aria-hidden`): put the step's number in the title too if it matters (“Step 1: …”). Ignored by a `dot` root.
timestampReactNodeRight-aligned meta (e.g. a date) on the title row.
descriptionReactNodeSecondary line under the title.
detailReactNodeRich block content under the title/description, indented with the rail — the slot composing consumers (e.g. `@elabs-ai/components-ai`'s `AgentStep`, #192) interleave per node. Block-level, so it must NOT ride the inline title slot (`children`).

Also accepts: LiHTMLAttributes<HTMLLIElement>

TimelineRoot

PropTypeDescription
variantTimelineVariant`"status"` (default): every node carries the canonical 7-state `Status` — a process rail (runs, approvals, steps). `"plain"`: a CHRONOLOGY — nodes are neutral marks with no status semantics (milestones, releases, a history); the one `current` item gets the accent node and `aria-current="step"`. @default "status"
orientationTimelineOrientation`"vertical"` (default): the rail runs down the start edge. `"horizontal"`: items sit side by side on one connector, node on top. `"responsive"`: vertical below the root’s `@3xl` container width, horizontal from there — the milestone strip that stacks on a phone. @default "vertical"
nodeSizeTimelineNodeSize`"dot"` (default): a 12px mark. `"badge"`: a 32px disc that can carry an item's `node` content — a step number, a glyph — for a “how it works” rail. The item padding and connector move with it. @default "dot"

Also accepts: HTMLAttributes<HTMLOListElement>