Timeline

Maya Chen opened #482
Oct 2, 9:14
Add retry with backoff to the webhook dispatcher.
Jonas Weber left a review
Oct 2, 11:40
Looks good. Can we cap the delay at 30 seconds?
Maya Chen merged into main
Oct 3, 8:05

import {
  GitMergeIcon,
  GitPullRequestIcon,
  MessageSquareIcon,
} from "lucide-react";
import {
  Timeline,
  TimelineContent,
  TimelineDescription,
  TimelineHeader,
  TimelineIndicator,
  TimelineItem,
  TimelineTime,
  TimelineTitle,
} from "@/components/ui/timeline";

export default function TimelineDemo() {
  return (
    <Timeline className="w-full max-w-md">
      <TimelineItem>
        <TimelineIndicator>
          <GitPullRequestIcon />
        </TimelineIndicator>
        <TimelineContent>
          <TimelineHeader>
            <TimelineTitle>
              <strong>Maya Chen</strong> opened #482
            </TimelineTitle>
            <TimelineTime dateTime="2026-10-02T09:14">Oct 2, 9:14</TimelineTime>
          </TimelineHeader>
          <TimelineDescription>
            Add retry with backoff to the webhook dispatcher.
          </TimelineDescription>
        </TimelineContent>
      </TimelineItem>
      <TimelineItem>
        <TimelineIndicator>
          <MessageSquareIcon />
        </TimelineIndicator>
        <TimelineContent>
          <TimelineHeader>
            <TimelineTitle>
              <strong>Jonas Weber</strong> left a review
            </TimelineTitle>
            <TimelineTime dateTime="2026-10-02T11:40">
              Oct 2, 11:40
            </TimelineTime>
          </TimelineHeader>
          <TimelineDescription>
            Looks good. Can we cap the delay at 30 seconds?
          </TimelineDescription>
        </TimelineContent>
      </TimelineItem>
      <TimelineItem>
        <TimelineIndicator color="brand">
          <GitMergeIcon />
        </TimelineIndicator>
        <TimelineContent>
          <TimelineHeader>
            <TimelineTitle>
              <strong>Maya Chen</strong> merged into main
            </TimelineTitle>
            <TimelineTime dateTime="2026-10-03T08:05">Oct 3, 8:05</TimelineTime>
          </TimelineHeader>
        </TimelineContent>
      </TimelineItem>
    </Timeline>
  );
}

Installation

$ pnpm dlx shadcn@latest add @desyne/timeline

The CLI installs dependencies and any other components this one uses.

Usage

tsx

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

tsx

<Timeline aria-label="Shipment history">
  <TimelineItem>
    <TimelineIndicator color="success" />
    <TimelineContent>
      <TimelineHeader>
        <TimelineTitle>Order delivered</TimelineTitle>
        <TimelineTime dateTime="2026-10-04T14:41">Today, 2:41 PM</TimelineTime>
      </TimelineHeader>
      <TimelineDescription>Left at the front door</TimelineDescription>
    </TimelineContent>
  </TimelineItem>
</Timeline>

The timeline is static markup with no "use client", so it renders in server components.

When to use

Timeline: things that already happened, in order, where when they happened matters (activity, history, audit logs, tracking).
Stepper: steps the user still has to complete.
Item: a list of entities, not events.
Table: large logs that users filter, sort or export.

Anatomy

tsx

<Timeline>                     {/* <ol>, variant, connector */}
  <TimelineItem>               {/* <li> */}
    <TimelineIndicator />      {/* dot, icon tile or media + connector */}
    <TimelineContent>          {/* fills the rest of the row */}
      <TimelineHeader>         {/* title and time on one row */}
        <TimelineTitle />
        <TimelineTime />       {/* <time> */}
      </TimelineHeader>
      <TimelineDescription />  {/* body text or any content */}
    </TimelineContent>
  </TimelineItem>
</Timeline>

Part	Renders	Notes
`Timeline`	`<ol>`	Sets `--timeline-indicator` (marker size) and `--timeline-gap` (space between items) for the chosen `variant`.
`TimelineItem`	`<li>`	A row: marker column plus content.
`TimelineIndicator`	`<div aria-hidden>`	With no children, a dot. With children, a 28px round icon tile (`variant="icon"`) or a circle that an image or avatar fills (`variant="media"`). Draws the connector down to the next item.
`TimelineContent`	`<div>`	Aligns its first line with the marker and adds the gap below each item.
`TimelineHeader`	`<div>`	Flex row that wraps. The time is pushed to the end.
`TimelineTitle`	`<div>`	Foreground text. `<strong>` inside is medium weight, for names.
`TimelineTime`	`<time>`	Muted, tabular. Pass `dateTime` with an ISO value.
`TimelineDescription`	`<div>`	Muted body text. Can hold badges, quotes or cards.

Examples

Dots

Leave TimelineIndicator empty for a dot. Without color it's a neutral ring; with color it's filled with a soft halo, useful for the latest or most important event.

Order delivered
Today, 2:41 PM
Left at the front door · Signed by R. Patel
Out for delivery
Today, 8:02 AM
Van 14 · Brooklyn depot
Arrived at local depot
Oct 3, 9:47 PM
Brooklyn, NY
Shipped
Oct 2, 4:15 PM
Northfold warehouse, Newark, NJ

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

const events = [
  {
    title: "Order delivered",
    detail: "Left at the front door · Signed by R. Patel",
    time: "Today, 2:41 PM",
    iso: "2026-10-04T14:41",
    color: "success",
  },
  {
    title: "Out for delivery",
    detail: "Van 14 · Brooklyn depot",
    time: "Today, 8:02 AM",
    iso: "2026-10-04T08:02",
  },
  {
    title: "Arrived at local depot",
    detail: "Brooklyn, NY",
    time: "Oct 3, 9:47 PM",
    iso: "2026-10-03T21:47",
  },
  {
    title: "Shipped",
    detail: "Northfold warehouse, Newark, NJ",
    time: "Oct 2, 4:15 PM",
    iso: "2026-10-02T16:15",
  },
] as const;

export default function TimelineDots() {
  return (
    <Timeline className="w-full max-w-md" aria-label="Shipment history">
      {events.map((e) => (
        <TimelineItem key={e.iso}>
          <TimelineIndicator color={"color" in e ? e.color : undefined} />
          <TimelineContent>
            <TimelineHeader>
              <TimelineTitle className="font-medium">{e.title}</TimelineTitle>
              <TimelineTime dateTime={e.iso}>{e.time}</TimelineTime>
            </TimelineHeader>
            <TimelineDescription>{e.detail}</TimelineDescription>
          </TimelineContent>
        </TimelineItem>
      ))}
    </Timeline>
  );
}

Compact

variant="compact" shrinks markers to 20px and tightens spacing for dense activity feeds in sidebars and popovers.

Ana changed status to In review
2m ago
Ana attached spec-v3.pdf
14m ago
Leo assigned the issue to Ana
1h ago
Leo added the label Billing
1h ago
Sam created the issue
3h ago

import {
  Timeline,
  TimelineContent,
  TimelineHeader,
  TimelineIndicator,
  TimelineItem,
  TimelineTime,
  TimelineTitle,
} from "@/components/ui/timeline";

const log = [
  {
    who: "Ana",
    what: "changed status to In review",
    ago: "2m",
    iso: "2026-10-04T10:58",
  },
  {
    who: "Ana",
    what: "attached spec-v3.pdf",
    ago: "14m",
    iso: "2026-10-04T10:46",
  },
  {
    who: "Leo",
    what: "assigned the issue to Ana",
    ago: "1h",
    iso: "2026-10-04T10:00",
  },
  {
    who: "Leo",
    what: "added the label Billing",
    ago: "1h",
    iso: "2026-10-04T09:58",
  },
  { who: "Sam", what: "created the issue", ago: "3h", iso: "2026-10-04T08:12" },
];

export default function TimelineCompact() {
  return (
    <Timeline
      variant="compact"
      className="w-full max-w-sm"
      aria-label="Activity"
    >
      {log.map((l) => (
        <TimelineItem key={l.iso}>
          <TimelineIndicator />
          <TimelineContent>
            <TimelineHeader>
              <TimelineTitle className="text-[0.8125rem]">
                <strong>{l.who}</strong>{" "}
                <span className="text-muted-foreground">{l.what}</span>
              </TimelineTitle>
              <TimelineTime dateTime={l.iso}>{l.ago} ago</TimelineTime>
            </TimelineHeader>
          </TimelineContent>
        </TimelineItem>
      ))}
    </Timeline>
  );
}

Rich content

Content can be anything: a quoted reply, a badge, an attachment. Use variant="media" to fill the marker with an Avatar or image.

Priya Raman replied
9:30 AM
I've refunded the duplicate charge. It should show on your statement within 5 business days.
Refund issued
9:28 AM
$129.00to Visa ending 4242
Daniel Kim opened the ticket
Yesterday
"I was charged twice for my October subscription."

import { FileTextIcon } from "lucide-react";
import { Avatar } from "@/components/ui/avatar";
import { Badge } from "@/components/ui/badge";
import {
  Timeline,
  TimelineContent,
  TimelineDescription,
  TimelineHeader,
  TimelineIndicator,
  TimelineItem,
  TimelineTime,
  TimelineTitle,
} from "@/components/ui/timeline";

export default function TimelineRichContent() {
  return (
    <Timeline className="w-full max-w-md" aria-label="Ticket history">
      <TimelineItem>
        <TimelineIndicator variant="media">
          <Avatar fallback="PR" colorful className="size-full" />
        </TimelineIndicator>
        <TimelineContent className="gap-2">
          <TimelineHeader>
            <TimelineTitle>
              <strong>Priya Raman</strong> replied
            </TimelineTitle>
            <TimelineTime dateTime="2026-10-04T09:30">9:30 AM</TimelineTime>
          </TimelineHeader>
          <div className="rounded-lg border bg-card px-3 py-2.5 text-sm leading-relaxed shadow-[0_1px_2px_rgb(0_0_0/0.04)]">
            I've refunded the duplicate charge. It should show on your statement
            within 5 business days.
          </div>
        </TimelineContent>
      </TimelineItem>
      <TimelineItem>
        <TimelineIndicator>
          <FileTextIcon />
        </TimelineIndicator>
        <TimelineContent className="gap-2">
          <TimelineHeader>
            <TimelineTitle>
              <strong>Refund issued</strong>
            </TimelineTitle>
            <TimelineTime dateTime="2026-10-04T09:28">9:28 AM</TimelineTime>
          </TimelineHeader>
          <TimelineDescription className="flex flex-wrap items-center gap-2">
            <Badge size="sm" variant="soft" color="success">
              $129.00
            </Badge>
            to Visa ending 4242
          </TimelineDescription>
        </TimelineContent>
      </TimelineItem>
      <TimelineItem>
        <TimelineIndicator variant="media">
          <Avatar fallback="DK" colorful className="size-full" />
        </TimelineIndicator>
        <TimelineContent>
          <TimelineHeader>
            <TimelineTitle>
              <strong>Daniel Kim</strong> opened the ticket
            </TimelineTitle>
            <TimelineTime dateTime="2026-10-03T18:02">Yesterday</TimelineTime>
          </TimelineHeader>
          <TimelineDescription>
            "I was charged twice for my October subscription."
          </TimelineDescription>
        </TimelineContent>
      </TimelineItem>
    </Timeline>
  );
}

Without connector

connector={false} hides the lines (spacing stays the same), for feeds where items aren't a single continuous sequence.

Payment received
Oct 1
$480.00 for the Team plan, invoice INV-2041.
3 seats added
Sep 24
Prorated charge of $36.00 on the next invoice.
Card expiring soon
Sep 15
Visa ending 4242 expires at the end of October.

import { CheckCircle2Icon, CreditCardIcon, UserPlusIcon } from "lucide-react";
import {
  Timeline,
  TimelineContent,
  TimelineDescription,
  TimelineHeader,
  TimelineIndicator,
  TimelineItem,
  TimelineTime,
  TimelineTitle,
} from "@/components/ui/timeline";

export default function TimelineWithoutConnector() {
  return (
    <Timeline
      connector={false}
      className="w-full max-w-md"
      aria-label="Account events"
    >
      <TimelineItem>
        <TimelineIndicator color="success">
          <CheckCircle2Icon />
        </TimelineIndicator>
        <TimelineContent>
          <TimelineHeader>
            <TimelineTitle className="font-medium">
              Payment received
            </TimelineTitle>
            <TimelineTime dateTime="2026-10-01">Oct 1</TimelineTime>
          </TimelineHeader>
          <TimelineDescription>
            $480.00 for the Team plan, invoice INV-2041.
          </TimelineDescription>
        </TimelineContent>
      </TimelineItem>
      <TimelineItem>
        <TimelineIndicator color="info">
          <UserPlusIcon />
        </TimelineIndicator>
        <TimelineContent>
          <TimelineHeader>
            <TimelineTitle className="font-medium">3 seats added</TimelineTitle>
            <TimelineTime dateTime="2026-09-24">Sep 24</TimelineTime>
          </TimelineHeader>
          <TimelineDescription>
            Prorated charge of $36.00 on the next invoice.
          </TimelineDescription>
        </TimelineContent>
      </TimelineItem>
      <TimelineItem>
        <TimelineIndicator color="warning">
          <CreditCardIcon />
        </TimelineIndicator>
        <TimelineContent>
          <TimelineHeader>
            <TimelineTitle className="font-medium">
              Card expiring soon
            </TimelineTitle>
            <TimelineTime dateTime="2026-09-15">Sep 15</TimelineTime>
          </TimelineHeader>
          <TimelineDescription>
            Visa ending 4242 expires at the end of October.
          </TimelineDescription>
        </TimelineContent>
      </TimelineItem>
    </Timeline>
  );
}

Accessibility

The timeline is an <ol>, so screen readers announce the number of events. Add an aria-label when the context doesn't already make clear what the list is.
Markers are aria-hidden. If an icon or color carries meaning (e.g. failed vs. succeeded), say so in the title or description too.
TimelineTime renders a <time> element; pass a machine-readable dateTime alongside friendly text like "2h ago".
TimelineTitle is a <div>. If items are sections with their own headings, put a heading element inside it.

Styling

Data attributes

Attribute	On	Values
`data-slot="timeline"`	`Timeline`	Always
`data-variant`	`Timeline`	`default` · `compact`
`data-connector`	`Timeline`	`true` · `false`
`data-slot="timeline-item"`	`TimelineItem`	Always
`data-slot="timeline-indicator"`	Marker column	Always
`data-slot="timeline-dot"`	Dot	No children
`data-slot="timeline-connector"`	Line	Always (hidden on the last item)
`data-slot="timeline-content"` / `-header` / `-title` / `-time` / `-description`	Parts	Always

CSS variables

Variable	Default	Compact	Used for
`--timeline-indicator`	`--spacing(7)` (28px)	`--spacing(5)` (20px)	Marker size and column width
`--timeline-gap`	`--spacing(6)`	`--spacing(3.5)`	Space under each item