# Timeline

A vertical sequence of dated, dot-connected events.

- Category: Core Elements
- Page: https://wunderui.com/components/timeline
- Tier: Free

## Install

```bash
npx wunderui-cli add timeline
```

## Import

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

## Minimal usage

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.

## Usage

```tsx
import { Timeline } from "@/components/ui/timeline"

export function OrderTimeline() {
  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" },
        { id: "delivered", title: "Delivered", description: "Signed for at the door", timestamp: "Nov 12" },
      ]}
    />
  )
}
```

## 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

- [Agenda](https://wunderui.com/components/agenda) for the events of a day with start and end times
- [Stepper](https://wunderui.com/components/stepper) for a progress indicator that people move through, such as a checkout
- [Run Timeline](https://wunderui.com/components/run-timeline) for the steps of an agent run with duration, tokens and input or output

## Behavior

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

- `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.
- `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.
- `Title`: The title of the entry in semibold text. It can be any React node, so keep it to a short sentence.
- `Timestamp`: 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.
- `Description`: The detail of the entry, in secondary text under the title.
- `Connector`: 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.
- `TimelineEntry`
- `TimelineEvent`

## 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.
- 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.
- 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.
- Pass dot colours as tokens, such as var(--success) or var(--destructive). The glyph inside switches between white and dark so it stays readable.
- 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 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 write times like recently or a while ago. People can't tell which entry came first.

## API reference

### Timeline

| Prop | Type | Default | Description |
|---|---|---|---|
| items* | TimelineItem[] |  | The entries, in order. Each is `{ id, title, description?, timestamp?, icon?, avatar?, color? }`: `id` is the React key, `title` and `description` are React nodes, `timestamp` is printed as written, `icon` goes inside the dot, `avatar` replaces the dot and `color` is the fill of the dot. |
| className | string |  | Extra classes for the root element, merged after the defaults, for example a width or `min-w-[520px]` for a row inside a scroll container. |
| compact | boolean | false | Smaller dots, icons, text and gaps, for long lists and small cards. The default is off. |
| orientation | "vertical" \| "horizontal" | "vertical" | `vertical` stacks the entries in a column. `horizontal` lays them out in a row, each with an equal share of the width and the time above its dot. The default is `vertical`. |

### TimelineEntry

| Prop | Type | Default | Description |
|---|---|---|---|
| title* | 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 …). |
| className | string |  |  |
| 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 |  |  |

### TimelineEvent

| Prop | Type | Default | Description |
|---|---|---|---|
| title* | 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 …). |
| className | string |  |  |
| 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 |  |  |

## Examples

### Layout: vertical or horizontal, default or compact

```tsx
import { Timeline } from "@/components/ui/timeline"

export function OrderTimeline() {
  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" },
        { id: "delivered", title: "Delivered", description: "Signed for at the door", timestamp: "Nov 12" },
      ]}
    />
  )
}
```

### Dot: the plain point, an icon, a colour or a person

```tsx
import { Timeline } from "@/components/ui/timeline"

export function OrderTimeline() {
  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" },
        { id: "delivered", title: "Delivered", description: "Signed for at the door", timestamp: "Nov 12" },
      ]}
    />
  )
}
```

### Status: in progress, completed, failed and cancelled

```tsx
import { Timeline } from "@/components/ui/timeline"
import { Check, CircleDashed } from "lucide-react"

export function DeployTimeline() {
  return (
    <Timeline
      items={[
        {
          id: "build",
          title: "Build",
          description: "Passed in 48 s",
          timestamp: "09:14",
          color: "var(--success)",
          icon: <Check className="size-3.5" />,
        },
        { id: "tests", title: "Tests", description: "412 of 640 done", timestamp: "09:15" },
        {
          id: "deploy",
          title: "Deploy",
          description: "Waits for the tests",
          color: "var(--muted)",
          icon: <CircleDashed className="size-3.5" />,
        },
      ]}
    />
  )
}
```

### Content: title, time, description or all three

```tsx
import { Timeline } from "@/components/ui/timeline"

export function OrderTimeline() {
  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" },
        { id: "delivered", title: "Delivered", description: "Signed for at the door", timestamp: "Nov 12" },
      ]}
    />
  )
}
```

### Entry mark: the tone of the status dot, and a custom icon

```tsx
import { TimelineEntry } from "@/components/ui/timeline"
import { Clock } from "lucide-react"

export function PullRequest() {
  return (
    <div className="flex flex-col">
      <TimelineEntry
        status={{ tone: "success" }}
        title="Pull request merged"
        meta="Nov 9 · 14:25"
      />
      <TimelineEntry
        status={{ tone: "muted", icon: <Clock /> }}
        title="Release scheduled"
        meta="Nov 12"
        last
      />
    </div>
  )
}
```

### Entry content: time, object chip, meta line, comment or badge

```tsx
import { TimelineEntry } from "@/components/ui/timeline"

export function Entry() {
  return (
    <div className="flex flex-col">
      <TimelineEntry
        avatar={{ initials: "NL", color: "indigo" }}
        title={<><strong>Nora Lindgren</strong> created project <strong>Checkout redesign</strong></>}
        time="10:42 AM"
        object={{ label: "Checkout redesign" }}
        last
      />
    </div>
  )
}
```

### Entry connector: a line, a green line, or none on the last entry

```tsx
import { TimelineEntry } from "@/components/ui/timeline"
import { FileText } from "lucide-react"

export function Entries() {
  return (
    <div className="flex flex-col">
      <TimelineEntry
        avatar={{ initials: "NL", color: "indigo" }}
        title={<><strong>Nora Lindgren</strong> created project <strong>Checkout redesign</strong></>}
        time="10:42 AM"
        object={{ label: "Checkout redesign" }}
      />
      <TimelineEntry
        avatar={{ initials: "PR", color: "purple" }}
        title={<><strong>Priya Raman</strong> moved <strong>Q4 report</strong> to Done</>}
        time="Yesterday"
        object={{ icon: <FileText />, label: "Q4 report" }}
        last
      />
    </div>
  )
}
```

## In context

### Parcel tracking: a Widget around a Timeline

```tsx
import { Timeline } from "@/components/ui/timeline"
import { Widget } from "@/components/ui/widget"
import { Badge } from "@/components/ui/badge"
import { Check, CircleDashed } from "lucide-react"

export function ParcelTracking() {
  return (
    <Widget
      title="Order 1,842"
      description="Estimated delivery Nov 12"
      action={
        <Badge color="indigo" badgeStyle="light" shape="pill">
          In transit
        </Badge>
      }
      className="w-full max-w-[400px]"
    >
      <Timeline
        items={[
          {
            id: "placed",
            title: "Order placed",
            timestamp: "Nov 9, 09:14",
            color: "var(--success)",
            icon: <Check className="size-3.5" />,
          },
          {
            id: "packed",
            title: "Packed",
            timestamp: "Nov 10, 08:02",
            color: "var(--success)",
            icon: <Check className="size-3.5" />,
          },
          { id: "shipped", title: "Shipped", description: "On its way to Hamburg", timestamp: "Nov 10, 16:40" },
          {
            id: "delivered",
            title: "Delivered",
            description: "Expected Nov 12",
            color: "var(--muted)",
            icon: <CircleDashed className="size-3.5" />,
          },
        ]}
      />
    </Widget>
  )
}
```

### Project activity: people instead of dots

```tsx
import { Timeline } from "@/components/ui/timeline"
import { Widget } from "@/components/ui/widget"
import { Button } from "@/components/ui/button"
import { Avatar, AvatarFallback } from "@/components/ui/avatar"

export function ProjectActivity() {
  return (
    <Widget
      title="Project activity"
      description="Checkout redesign"
      action={<Button variant="plain" size="sm">View all</Button>}
      className="w-full max-w-[480px]"
    >
      <Timeline
        items={[
          {
            id: "comment",
            title: "Nora Lindgren commented on Checkout redesign",
            description: "The address step needs a clearer error state.",
            timestamp: "10 min ago",
            avatar: <Avatar size="sm" color="indigo"><AvatarFallback>NL</AvatarFallback></Avatar>,
          },
          {
            id: "moved",
            title: "Daniel Okafor moved Billing FAQ to Review",
            timestamp: "1 h ago",
            avatar: <Avatar size="sm" color="blue"><AvatarFallback>DO</AvatarFallback></Avatar>,
          },
          {
            id: "files",
            title: "Priya Raman uploaded 3 files",
            description: "tokens.json, hero.png and brand-guide.pdf",
            timestamp: "Yesterday",
            avatar: <Avatar size="sm" color="purple"><AvatarFallback>PR</AvatarFallback></Avatar>,
          },
          {
            id: "joined",
            title: "Maya Kessler joined the project",
            timestamp: "Nov 8",
            avatar: <Avatar size="sm" color="green"><AvatarFallback>MK</AvatarFallback></Avatar>,
          },
        ]}
      />
    </Widget>
  )
}
```

### Roadmap: a row on a wide screen, a list on a narrow one

```tsx
import { Timeline } from "@/components/ui/timeline"
import { Widget } from "@/components/ui/widget"
import { Check, Rocket } from "lucide-react"

export function Roadmap() {
  return (
    <Widget title="Roadmap" description="Checkout redesign, 2027" className="w-full max-w-[560px]">
      <div className="overflow-x-auto">
        <Timeline
          orientation="horizontal"
          className="min-w-[520px]"
          items={[
            {
              id: "kickoff",
              title: "Kick-off",
              description: "Scope agreed",
              timestamp: "Mar 3",
              color: "var(--success)",
              icon: <Check className="size-3.5" />,
            },
            {
              id: "prototype",
              title: "Prototype",
              description: "Checkout clickable",
              timestamp: "Apr 14",
              color: "var(--success)",
              icon: <Check className="size-3.5" />,
            },
            { id: "beta", title: "Beta", description: "20 customers", timestamp: "Jun 2" },
            {
              id: "launch",
              title: "Launch",
              description: "Everyone gets it",
              timestamp: "Jul 21",
              color: "var(--muted)",
              icon: <Rocket className="size-3.5" />,
            },
          ]}
        />
      </div>
    </Widget>
  )
}
```

### Invoice history: the steps of an invoice, open and paid

```tsx
import { TimelineEntry } from "@/components/ui/timeline"
import { Widget } from "@/components/ui/widget"
import { Clock } from "lucide-react"

export function InvoiceHistory() {
  return (
    <Widget title="Invoice 1,842" description="WunderUI, billed to info@wunderui.com" className="w-full max-w-[520px]">
      <div className="flex flex-col">
        <TimelineEntry
          status={{ tone: "success" }}
          title="Invoice created"
          badge="$2,010.50"
          badgeColor="grey"
          meta="Nov 9, 2026 · 14:20 · by Nora Lindgren"
        />
        <TimelineEntry
          status={{ tone: "success" }}
          title="Invoice sent"
          badge="Sent"
          badgeColor="indigo"
          meta="Nov 9, 2026 · 14:22 · to info@wunderui.com"
        />
        <TimelineEntry
          status={{ tone: "muted", icon: <Clock /> }}
          title="Payment due"
          badge="Nov 20"
          badgeColor="grey"
          meta="In 11 days"
          last
        />
      </div>
    </Widget>
  )
}
```

### Release history: one tone and icon per step

```tsx
import { TimelineEntry } from "@/components/ui/timeline"
import { Widget } from "@/components/ui/widget"
import { CircleAlert, GitMerge, MessageSquare, Rocket } from "lucide-react"

export function ReleaseHistory() {
  return (
    <Widget title="Release history" description="Pull request 482" className="w-full max-w-[520px]">
      <div className="flex flex-col">
        <TimelineEntry
          status={{ tone: "muted", icon: <MessageSquare /> }}
          title="Pull request opened"
          meta="Nov 8 · 10:12"
        />
        <TimelineEntry
          status={{ tone: "warning", icon: <CircleAlert /> }}
          title="Changes requested"
          badge="2 comments"
          badgeColor="yellow"
          meta="Nov 8 · 15:30"
        />
        <TimelineEntry
          status={{ tone: "success", icon: <GitMerge /> }}
          title="Merged into main"
          badge="v2.4.0"
          badgeColor="green"
          meta="Nov 9 · 14:25"
        />
        <TimelineEntry
          status={{ tone: "primary", icon: <Rocket /> }}
          title="Released to production"
          meta="Nov 9 · 14:40"
          last
        />
      </div>
    </Widget>
  )
}
```

## For AI agents

`get_component("timeline")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
