Timeline
FreeA sequence of dated events joined by a line, drawn from data, as a list or as a row.
npx wunderui-cli add timelinePlayground
Order placed
Nov 9Confirmed by email
Shipped
Nov 10Left the warehouse
Delivered
Nov 12Signed for at the door
Order placed
Nov 9Confirmed by email
Shipped
Nov 10Left the warehouse
Delivered
Nov 12Signed for at the door
Order placed
Confirmed by email
Shipped
Left the warehouse
Delivered
Signed for at the door
Installation
npx wunderui-cli add timelineWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { Timeline, TimelineEntry } from "@/components/wunderui/timeline"
import type {
TimelineEntryProps,
TimelineItem,
} from "@/components/wunderui/timeline"Then use it:
import { Timeline } from "@/components/ui/timeline"
export function Order() {
return (
<Timeline
items={[
{ id: "placed", title: "Order placed", description: "Confirmed by email", timestamp: "Nov 9" },
{ id: "shipped", title: "Shipped", description: "Left the warehouse", timestamp: "Nov 10" },
]}
/>
)
}Expected result: Two entries in a column, each with a dot, a bold title, the date next to it and the description below. A line joins the two dots.
When to use
Use Timeline for
- The steps of an order, a shipment or an application, in the order they happen
- Project milestones and release histories drawn from data
- A deploy or an audit log, where each entry has a time and a short result
- A compact activity feed with a person at each entry
Use something else for
- Agenda for the events of a day with start and end times
- Stepper for a progress indicator that people move through, such as a checkout
- Run Timeline for the steps of an agent run with duration, tokens and input or output
Layout
Entries stack in a column by default. Horizontal lays them out in a row with the time above each dot, and compact shrinks dots, text and gaps for long lists.
Order placed
Nov 9Confirmed by email
Shipped
Nov 10Left the warehouse
Delivered
Nov 12Signed for at the door
Order placed
Nov 9Confirmed by email
Shipped
Nov 10Left the warehouse
Delivered
Nov 12Signed for at the door
Order placed
Confirmed by email
Shipped
Left the warehouse
Delivered
Signed for at the door
Order placed
Confirmed by email
Shipped
Left the warehouse
Delivered
Signed for at the door
Dot
The marker of an entry is a small point. Give it an icon or a colour, or replace it with a person for an activity feed.
Order placed
Nov 9Confirmed by email
Shipped
Nov 10Left the warehouse
Delivered
Nov 12Signed for at the door
Order placed
Nov 9Confirmed by email
Shipped
Nov 10Left the warehouse
Delivered
Nov 12Signed for at the door
Order placed
Nov 9Confirmed by email
Shipped
Nov 10Left the warehouse
Delivered
Nov 12Signed for at the door
Nora Lindgren placed the order
Nov 9Confirmed by email
Daniel Okafor shipped it
Nov 10Left the warehouse
Priya Raman received it
Nov 12Signed for at the door
Status
There is no status prop. Completed, current, upcoming, failed and cancelled come from the colour and icon of the dot, which stays readable on every fill.
Build
09:14Passed in 48 s
Tests
09:15412 of 640 done
Deploy
Waits for the tests
Build
09:14Passed in 48 s
Tests
09:19640 of 640 passed
Deploy
09:21Live on production
Build
09:14Passed in 48 s
Tests
09:193 of 640 failed
Deploy
Did not start
Build
09:14Passed in 48 s
Tests
09:16Stopped by Maya Kessler
Deploy
Did not start
Content
Every entry needs an id and a title. The description and timestamp are optional, and the timestamp sits next to the title, or above the dot in a row.
Order placed
Shipped
Delivered
Order placed
Nov 9Shipped
Nov 10Delivered
Nov 12Order placed
Confirmed by email
Shipped
Left the warehouse
Delivered
Signed for at the door
Order placed
Nov 9Confirmed by email
Shipped
Nov 10Left the warehouse
Delivered
Nov 12Signed for at the door
Activity entry
TimelineEntry is one rich entry you compose yourself, for an activity feed or a history: an avatar for an event or a round status mark for a step (four tones, a check by default), a sentence with the names in strong text, a time or badge on the right, an object chip, a meta line and any content below as children. Every entry draws a line down to the next one, a success mark turns it green, and the last entry sets last to leave it out. It replaces TimelineEvent.
Entry mark
Pull request merged
Nov 9 · 14:25
Release scheduled
Nov 12
Pull request merged
Nov 9 · 14:25
Release scheduled
Nov 12
Pull request merged
Nov 9 · 14:25
Release scheduled
Nov 12
Pull request merged
Nov 9 · 14:25
Release scheduled
Nov 12
Pull request merged
Nov 9 · 14:25
Release scheduled
Nov 12
Entry content
Nora Lindgren created project Checkout redesign
10:42 AMNora Lindgren created project Checkout redesign
10:42 AMPriya Raman moved Q4 report to Done
YesterdayMoved from In review · Nov 8, 16:05
Daniel Okafor commented on Billing FAQ
9:15 AMThe refund wording still needs a review from legal.
Invoice created
$2,010.50Nov 9, 2026 · 14:20 · by Nora Lindgren
Entry connector
Nora Lindgren created project Checkout redesign
10:42 AMPriya Raman moved Q4 report to Done
YesterdayInvoice created
$2,010.50Payment due
Nov 20Nora Lindgren created project Checkout redesign
10:42 AMBehavior and motion
What the Timeline does with its data, its direction, the dot colour and motion.
- Entries are data
- Pass the items. Each needs an id and a title, and description, timestamp, icon, avatar and colour are optional, while the id is only the React key and isn't shown.
- Vertical and horizontal
- Vertical stacks entries in a column with the dot on the left. Horizontal lays them in a row with equal widths, so at about 120 px per entry scroll it or go vertical on narrow screens.
- Compact
- Compact shrinks the dot to 16 px, its icon to 10 px, the text to 12 px and the gap between entries from 24 to 16 px. An avatar keeps its own size.
- The colour of the dot
- The colour is any CSS colour, a token included, and defaults to primary. The glyph inside switches between white and dark to keep WCAG contrast, also when a token changes in dark mode.
- No status prop
- Completed, current, upcoming, failed and cancelled aren't props. Build them from colour and icon: green with a check, the default dot, a quiet colour with a dashed circle, red with a cross.
- A person instead of a dot
- A small Avatar replaces the dot and sits on the line the same way. Use it for an activity feed, and name the person in the title.
- Plain markup
- It is a plain div, not a list, and nothing in it is a control. Give it a heading nearby and put the status in the text, because the colour of a dot isn't announced.
- Motion and reduced motion
- It adds no animation: entries appear at once and nothing moves when the data changes. There is nothing to reduce, so no reduced-motion fallback is needed.
Anatomy
The parts of a vertical Timeline with two entries, numbered in the figure.
Shipped
Nov 10Delivered
Nov 12Signed for at the door
- 1data-slot="timeline"
Draws the entries, stacked in a column or laid out in a row, and joins them with a line. Compact makes dots, text and gaps smaller, and it is a plain div, not a list.
- 2data-slot="timeline-dot"
The marker of an entry: a 24 px circle (16 px when compact) in the entry's colour, with an icon or a small point inside. An avatar replaces it.
- 3
The title of the entry in semibold text. It can be any React node, so keep it to a short sentence.
- 4Optional
The timestamp in small tertiary text, printed as written. It sits next to the title in a column and above the dot in a row.
- 5Optional
The detail of the entry, in secondary text under the title.
- Optional
A 1 px line in the border colour from one dot to the next. The last entry has none, and it isn't numbered because it runs between two dots.
- data-slot="timeline-entry"Optional
- Optional
Best practices
- Do
Pass a stable id for every entry. It is the React key, so a list that grows at the top keeps its rows.
- Do
Give every timestamp a date or a time with its unit, such as Nov 9, 09:14 or 3 min ago. It prints as written, so format it yourself and use one style in the whole list.
- Do
Say the status in words, in the title or description: Tests failed, not just a red dot. Colour and icon are decoration for people who can see them.
- Do
Pass dot colours as tokens, such as var(--success) or var(--destructive). The glyph inside switches between white and dark so it stays readable.
- Do
Use compact for long lists and for a Timeline inside a small card. Dots, text and gaps shrink so more entries fit.
- Don’t
Don't use a horizontal Timeline for more than four or five entries. Each entry gets an equal share of the width, so a long row squeezes the text.
- Don’t
Don't put long paragraphs, buttons or links in the title or description. For one rich entry with a comment, object chip or attachments, use a Timeline Event.
- Don’t
Don't write times like recently or a while ago. People can't tell which entry came first.
API reference
Timeline is a plain component: it takes the props below and passes nothing else on to its element.
Draws the entries, stacked in a column or laid out in a row, and joins them with a line. Compact makes dots, text and gaps smaller, and it is a plain div, not a list.
| Prop | Type | Default | Description |
|---|---|---|---|
| items required | TimelineItem[] | — | The entries, in order. Each is : is the React key, and are React nodes, is printed as written, goes inside the dot, replaces the dot and is the fill of the dot. |
| orientation | "vertical" | "horizontal" | "vertical" | stacks the entries in a column. lays them out in a row, each with an equal share of the width and the time above its dot. The default is . |
| compact | boolean | false | Smaller dots, icons, text and gaps, for long lists and small cards. The default is off. |
| className | string | — | Extra classes for the root element, merged after the defaults, for example a width or for a row inside a scroll container. |
| Prop | Type | Default | Description |
|---|---|---|---|
| title required | ReactNode | — | |
| avatar | { src?: string; initials?: string; color?: AvatarColor } | — | Actor avatar (Type=event). |
| badge | ReactNode | — | Trailing badge/label on the title row (Type=step). |
| badgeColor | "indigo" | "blue" | "purple" | "pink" | "red" | "orange" | "yellow" | "green" | "alternative" | "grey" | "black" | "white" | "grey" | |
| children | ReactNode | — | Extra content below the title (comment excerpt, reactions, attachments …). |
| last | boolean | — | The last entry of the list: no connector line below it. |
| meta | ReactNode | — | |
| object | { icon?: ReactNode; label: ReactNode } | — | Small object chip under the title (Type=event) — e.g. project name. |
| status | { tone?: "success" | "primary" | "warning" | "muted"; icon?: ReactNode } | — | Status dot (Type=step): tone + icon. |
| time | ReactNode | — |
| Prop | Type | Default | Description |
|---|---|---|---|
| title required | ReactNode | — | |
| avatar | { src?: string; initials?: string; color?: AvatarColor } | — | Actor avatar (Type=event). |
| badge | ReactNode | — | Trailing badge/label on the title row (Type=step). |
| badgeColor | "indigo" | "blue" | "purple" | "pink" | "red" | "orange" | "yellow" | "green" | "alternative" | "grey" | "black" | "white" | — | |
| children | ReactNode | — | Extra content below the title (comment excerpt, reactions, attachments …). |
| last | boolean | — | The last entry of the list: no connector line below it. |
| meta | ReactNode | — | |
| object | { icon?: ReactNode; label: ReactNode } | — | Small object chip under the title (Type=event) — e.g. project name. |
| status | { tone?: "success" | "primary" | "warning" | "muted"; icon?: ReactNode } | — | Status dot (Type=step): tone + icon. |
| time | ReactNode | — |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("timeline")npx wunderui-cli add timelineThe full library index for assistants is at /llms.txt.
Related components
- Running: Comparing Figma and code tokenstokens.diff6.3sDone: Read 214 variables from Figmafigma.read3.6sFailed: Push to docs-preview timed out after 30 sgithub.push30.0sWaiting: Waiting for the previous step—AI & Agents4 stylesProActivity ItemOne line in a live activity stream: status, action, tool and elapsed time.
- Done420 tok$0.01640ms
Input
status: overdue, age: 30+ daysOutput
14 invoices, $42,860 in total - Done3,420 tok$0.042.1s
Input
14 invoice idsOutput
14 contacts, all with an email address - Running2,310 tok
Input
template: invoice-overdue-30 - Pending
Input
to: 14 recipients - PendingLog the result
AI & Agents5 stylesProRun TimelineEvery step of a run in order, with duration, tokens and expandable input/output.