Timeline

Read-only chronological history with structured titles, descriptions and semantic status markers.

Purpose

Use Timeline for read-only chronological history such as activity, status changes or audit events.

Event history

Build passed
Typecheck and registry validation completed.
Preview deployed
Ready for docs review.

import { Timeline, TimelineDescription, TimelineItem, TimelineTitle } from "@/components/ui/timeline";

export function Example() {
  return (
    <Timeline>
      <TimelineItem variant="success"><TimelineTitle>Build passed</TimelineTitle></TimelineItem>
    </Timeline>
  );
}

Installation

With the Siteplane registry alias configured, add the component and import the installed source from your app.

CLI

pnpm dlx shadcn@4.16.1 add @siteplane/timeline

Import

import { Timeline, TimelineDescription, TimelineItem, TimelineTitle } from "@/components/ui/timeline";

Need the machine-readable source metadata? View registry JSON.

Usage

Timeline is for read-only chronological events. Use Stepper when the user can move between steps.

import { Timeline, TimelineDescription, TimelineItem, TimelineTitle } from "@/components/ui/timeline";

export function Example() {
  return (
    <Timeline>
      <TimelineItem variant="success"><TimelineTitle>Build passed</TimelineTitle></TimelineItem>
    </Timeline>
  );
}

Examples

Semantic variants, marker shapes, icon markers and activity logs are props of the same primitive.

Variants

Default
Neutral entry without semantic status.
Accent
Highlights the primary event.
Info
Context was synced automatically.
Success
The step completed without issues.
Warning
An optional check is still pending.
Error
Sync failed; sign in again to retry.

<Timeline>
  <TimelineItem>...</TimelineItem>
  <TimelineItem variant="accent">...</TimelineItem>
  <TimelineItem variant="info">...</TimelineItem>
  <TimelineItem variant="success">...</TimelineItem>
  <TimelineItem variant="warning">...</TimelineItem>
  <TimelineItem variant="error">...</TimelineItem>
</Timeline>

Marker shapes

markerLabel exposes decorated markers to assistive technology as labeled images.

Dot
The default marker.
Ring
Outlined marker for open items.
Diamond
Rotated marker for notable events.
Bar
Elongated marker for phases.

<Timeline>
  <TimelineItem markerShape="dot">...</TimelineItem>
  <TimelineItem markerLabel="Needs review" markerShape="ring" variant="warning">
    ...
  </TimelineItem>
  <TimelineItem markerLabel="Information" markerShape="diamond" variant="info">
    ...
  </TimelineItem>
  <TimelineItem markerShape="bar" variant="accent">...</TimelineItem>
</Timeline>

Custom marker

marker swaps the dot for an icon; pair it with markerLabel for accessibility.

Migration finished
All records moved to the new schema.
v2.0 released
Published to the stable channel.

<Timeline>
  <TimelineItem marker={<CheckIcon />} markerLabel="Completed" variant="success">
    <TimelineTitle>Migration finished</TimelineTitle>
    <TimelineDescription>All records moved to the new schema.</TimelineDescription>
  </TimelineItem>
  <TimelineItem marker={<RocketIcon />} markerLabel="Released" variant="accent">
    <TimelineTitle>v2.0 released</TimelineTitle>
    <TimelineDescription>Published to the stable channel.</TimelineDescription>
  </TimelineItem>
</Timeline>

Activity log

Primitive reviewed
Look, behavior and states are signed off.
Docs updated
UI Lab page and agent rules refreshed.
Sync to consumers
Apps receive the updated files with the next release.

<Timeline>
  <TimelineItem variant="success">
    <TimelineTitle>Primitive reviewed</TimelineTitle>
    <TimelineDescription>Look, behavior and states are signed off.</TimelineDescription>
  </TimelineItem>
  <TimelineItem variant="info">
    <TimelineTitle>Docs updated</TimelineTitle>
    <TimelineDescription>UI Lab page and agent rules refreshed.</TimelineDescription>
  </TimelineItem>
  <TimelineItem variant="accent">
    <TimelineTitle>Sync to consumers</TimelineTitle>
    <TimelineDescription>Apps receive the updated files with the next release.</TimelineDescription>
  </TimelineItem>
</Timeline>

API Reference

The reference lists the source-owned exports and props that are easy to miss in visual examples. Inherited Base UI props remain available unless the wrapper narrows them.

Compose Timeline, TimelineItem, TimelineTitle and TimelineDescription.
TimelineItem accepts semantic status variants, an optional marker, and marker shapes bar, diamond, dot or ring.
Keep title, description and optional marker content in DOM order so chronology remains understandable without visual styling.

Motion

Component motion uses the shared Siteplane motion contract. See the global motion guide for provider setup, tokens and reduced-motion behavior.

Timeline is static by default and does not animate events on initial render.
State accents do not require a reduced-motion override.

Accessibility

Keep DOM order identical to the visual chronological order.
Status must remain readable in text or another non-color cue; marker color alone is not enough.
Timeline is read-only. Use Stepper when people can control or navigate process steps.

Implementation Guidance

Use status variants only for real semantic meaning, not decoration.
Do not turn a Timeline item into a hidden workflow button.
Prefer Stepper for interactive progress and Resource List for non-chronological entity collections.