Skip to content
WunderUI

Timeline

Free

A sequence of dated events joined by a line, drawn from data, as a list or as a row.

npx wunderui-cli add timeline

Playground

Order placed

Nov 9

Confirmed by email

Shipped

Nov 10

Left the warehouse

Delivered

Nov 12

Signed for at the door

Installation

bash
npx wunderui-cli add timeline

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
import { Timeline, TimelineEntry } from "@/components/wunderui/timeline"
import type {
  TimelineEntryProps,
  TimelineItem,
} from "@/components/wunderui/timeline"

Then use it:

tsx
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 9

Confirmed by email

Shipped

Nov 10

Left the warehouse

Delivered

Nov 12

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 9

Confirmed by email

Shipped

Nov 10

Left the warehouse

Delivered

Nov 12

Signed 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:14

Passed in 48 s

Tests

09:15

412 of 640 done

Deploy

Waits for the tests

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

Nov 9

Confirmed by email

Shipped

Nov 10

Left the warehouse

Delivered

Nov 12

Signed 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

Entry content

NL

Nora Lindgren created project Checkout redesign

10:42 AM
Checkout redesign

Entry connector

NL

Nora Lindgren created project Checkout redesign

10:42 AM
Checkout redesign
PR

Priya Raman moved Q4 report to Done

Yesterday
Q4 report

Behavior 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 10

Delivered

Nov 12

Signed for at the door

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

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

  • The title of the entry in semibold text. It can be any React node, so keep it to a short sentence.

  • Optional

    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.

  • Optional

    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.

PropTypeDefaultDescription
items requiredTimelineItem[]—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 .
compactbooleanfalseSmaller dots, icons, text and gaps, for long lists and small cards. The default is off.
classNamestring—Extra classes for the root element, merged after the defaults, for example a width or for a row inside a scroll container.

PropTypeDefaultDescription
title requiredReactNode—
avatar{ src?: string; initials?: string; color?: AvatarColor }—Actor avatar (Type=event).
badgeReactNode—Trailing badge/label on the title row (Type=step).
badgeColor"indigo" | "blue" | "purple" | "pink" | "red" | "orange" | "yellow" | "green" | "alternative" | "grey" | "black" | "white""grey"
childrenReactNode—Extra content below the title (comment excerpt, reactions, attachments …).
lastboolean—The last entry of the list: no connector line below it.
metaReactNode—
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.
timeReactNode—

PropTypeDefaultDescription
title requiredReactNode—
avatar{ src?: string; initials?: string; color?: AvatarColor }—Actor avatar (Type=event).
badgeReactNode—Trailing badge/label on the title row (Type=step).
badgeColor"indigo" | "blue" | "purple" | "pink" | "red" | "orange" | "yellow" | "green" | "alternative" | "grey" | "black" | "white"—
childrenReactNode—Extra content below the title (comment excerpt, reactions, attachments …).
lastboolean—The last entry of the list: no connector line below it.
metaReactNode—
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.
timeReactNode—

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("timeline")
Installnpx wunderui-cli add timeline

The full library index for assistants is at /llms.txt.