caliper uidocs
DemoSign inGet Pro

Timeline

Free

Events in order with dates and markers.

Installs components/ui/timeline.tsxDepends on lucide-reactMotion none in component source
pnpm dlx shadcn@latest add https://caliperui.site/r/timeline.json

  1. Monday

    Completed: Order placed

    Order NW-2210 · 3 items

  2. Completed: Payment captured

    Visa ending 4242

    Authorization 7F3A91 · Net $128.40 · Fee $3.99. Receipt sent to billing@northwind.example.

  3. Tuesday

    Completed: Packed at Leeds warehouse

  4. Today

    In progress: Out for delivery

    Courier will arrive between 1 and 3 PM

    Tracking ref LD-88-1204. The driver can be reached through the courier line if the address needs a gate code.

  5. Upcoming: Delivered

    Signature may be required

When to use #

Use it for

  • Showing history.

Skip it when

  • Items need columns; use a table.

Installation #

terminal
pnpm dlx shadcn@latest add https://caliperui.site/r/timeline.json

Adds its 2 files to components/ui/, each with its own stylesheet, and installs their packages. No account needed. The first part also adds Caliper UI’s tokens; import them once as in Installation.

Usage #

This is the code behind the preview above.

example.tsx
import { useState } from "react"
import { Timeline, type TimelineItem } from "@/components/ui/timeline"

const stages: TimelineItem[] = [
  { id: "open", title: "Order placed", description: "Order NW-2210 · 3 items", time: "Oct 6, 9:12 AM", datetime: "2026-10-06T09:12:00Z", status: "done", group: "Monday" },
  {
    id: "pay",
    title: "Payment captured",
    description: "Visa ending 4242",
    time: "Oct 6, 9:13 AM",
    datetime: "2026-10-06T09:13:00Z",
    status: "done",
    details: "Authorization 7F3A91 · Net $128.40 · Fee $3.99. Receipt sent to billing@northwind.example.",
  },
  { id: "pack", title: "Packed at Leeds warehouse", time: "Oct 7, 2:40 PM", datetime: "2026-10-07T14:40:00Z", status: "done", group: "Tuesday" },
  {
    id: "ship",
    title: "Out for delivery",
    description: "Courier will arrive between 1 and 3 PM",
    time: "Oct 8, 8:05 AM",
    datetime: "2026-10-08T08:05:00Z",
    status: "current",
    group: "Today",
    details: "Tracking ref LD-88-1204. The driver can be reached through the courier line if the address needs a gate code.",
  },
  { id: "deliver", title: "Delivered", description: "Signature may be required", status: "pending" },
];

export function TimelineDemo() {
  const [items] = useState(stages);
  return (
    <Timeline label="Order NW-2210" items={items} defaultExpanded={["ship"]} />
  );
}

API reference #

Timeline

component
PropTypeDefault
label *string—
items *readonly TimelineItem[]—
expandedreadonly string[]—
defaultExpandedreadonly string[][]
onExpandedChange((ids: string[]) => void)—
classNamestring—

Accessibility #

It is built on native elements and keeps aria-label, aria-hidden, aria-expanded and aria-controls in step with state.

No custom key handling; Tab and the native activation keys do the work.

Motion #

It declares no animation in its component source. Any transition comes from its stylesheet, which uses the duration tokens that collapse to instant under prefers-reduced-motion.