Skip to content
Design System
Contact

Timeline

Chronological activity grouped by day, with typed events and connectors.

Components<ol>

Playground

Activity on a deal, grouped by day with relative times for today. Filter by event type, or load older pages; they arrive after a short skeleton.

Preview
Demo data

Today

  1. Deploy pipeline shipped release 4.2.1 to production

    a3f9c2eReady in 1m 42s

  2. Priya Raman moved Acme Corporation renewal

    ReviewApproved

  3. Marcus Chen commented on Acme Corporation renewal

    Legal signed off on the SSO clause. We can send the order form today.

  4. Lena Fischer emailed Northwind

    Subject: Renewal pricing for 40 seats

Yesterday

  1. Priya Raman attached a file to Acme Corporation renewal

  2. Lena Fischer moved Acme Corporation renewal

    NegotiationReview

  3. Deploy pipeline failed to deploy to staging

    9be41d0Type check failed in billing/invoice.ts

Friday, Sep 25

  1. Lena Fischer commented on Acme Corporation renewal

    Sent the revised quote. Waiting on procurement.

  2. Lena Fischer created the deal Acme Corporation renewal

Props

Variant
Density
example.tsxtsx
1import { Timeline } from "@/components/ui/timeline"
2
3<Timeline
4  events={events}
5  filters={["comment", "status", "file", "deploy", "email", "created"]}
6  onLoadOlder={loadOlder}
7  hasMore={cursor !== null}
8/>

States

One event row in each state. Rows highlight on hover; attachments and links inside a row take focus.

States

    1. Marcus Chen commented on Acme Corporation renewal

      Legal signed off on the SSO clause. We can send the order form today.

    Defaultrest

    1. Priya Raman moved Acme Corporation renewal

      ReviewApproved
    Hover:hover

    1. Priya Raman attached a file to Acme Corporation renewal

    Focusattachment :focus-visible
  • Loadingaria-busy

    1. This comment was deleted by its author.

    Disableddeleted

    1. Deploy pipeline failed to deploy to staging

      9be41d0Type check failed in billing/invoice.ts

    Errorfailed deploy

    1. Deploy pipeline shipped release 4.2.1 to production

      a3f9c2eReady in 1m 42s

    Successdeploy ready

Examples

The compact variant for side panels, and project phases as a horizontal milestone timeline that scrolls inside its frame on phones.

Horizontal milestones
Demo data

Northwind customer portal

  1. Discovery

    Aug 3 – Aug 14

    Complete

  2. Design

    Aug 17 – Sep 4

    Complete

  3. Build

    Sep 7 – Oct 9

    In progress

    72%

  4. QA and beta

    Oct 12 – Oct 23

    Not started

  5. Launch

    Oct 28

    Not started

Compact, in a record side panel

Recent activity

  1. Deploy pipeline shipped release 4.2.1 to production

  2. Priya Raman moved Acme Corporation renewal to Approved

  3. Marcus Chen commented on Acme Corporation renewal

  4. Lena Fischer emailed Northwind

  5. Priya Raman attached a file to Acme Corporation renewal

API

PropTypeDefaultDescription
variant"default" | "compact" | "horizontal""default"Vertical feed with details, one-line compact rows, or horizontal milestones.
eventsTimelineEvent[]—Newest first. Each has a type, actor, local ISO time and type-specific details (status from and to, file, deploy, email subject).
itemsPhase[]—Horizontal variant only: name, date range, status and optional progress.
filtersEventType[]—Types offered as filter chips. Counts come from the loaded events.
onLoadOlder() => Promise<void>—Called by Load older; skeleton rows show until it resolves.
hasMorebooleanfalseShows Load older, or a note that this is where the record starts.
showConnectorsbooleantrueLines between event icons within a day.
showTimestampsbooleantrueRelative for today, clock time for earlier days; the full date is in the title.
density"comfortable" | "condensed""comfortable"Vertical spacing between events.

Accessibility

Keyboard

Move through filters, attachments and Load older
Tab
Toggle a filter or load older events
EnterorSpace
Scroll the milestone timeline once focused
←or→

Semantics and ARIA

  • Each day is a <section> labelled by its heading, with events in an ordered list, so screen readers can jump by day and hear the count.
  • Times are <time datetime> with the full date in a tooltip; relative labels are computed from a fixed date, so server and client agree.
  • Filter chips are toggle buttons with aria-pressed. Icons are decorative; the sentence carries the event type.
  • Load older sets aria-busy on the list and a polite status announces how many events arrived.
  • The milestone row is a focusable, labelled region that scrolls on its own, and the current phase has aria-current="step".