Timeline React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Timeline is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import Timeline from @/components/ui/timeline.

import { Phone, Receipt } from "lucide-react"
import { Timeline, type TimelineItemData } from "@/components/ui/timeline"

const activity: TimelineItemData[] = [
  {
    id: "payment",
    title: "Invoice #2026-0412 paid",
    description: "$12,480.00 by bank transfer",
    time: "2026-09-24T16:20:00",
    icon: <Receipt />,
    tone: "success",
  },
  {
    id: "call",
    title: "Call with Adam Foster",
    description: "12 min",
    time: "2026-09-23T11:05:00",
    icon: <Phone />,
    actor: { name: "Michael Reed", avatar: "/demo/mihai-ionescu.jpg" },
    details: "Asked for training for 2 new teammates.",
  },
]

export function ClientActivity() {
  return (
    <Timeline
      items={activity}
      locale="en-US"
    />
  )
}

// parts, for events the items API does not cover (same file, same look):
// TimelineRoot takes the appearance props of Timeline (variant, size, tone, color, line, timePosition,
//   timeFormat, locale, labels, classNames) and holds the shared clock and locale;
// TimelineGroup { label, sticky } is a day heading and its <ol>; without a label it is just the list;
// TimelineItem { status, tone, color, expanded, index } is one <li>; status only applies in the tracking
//   variant, where the current step gets aria-current="step";
// TimelineMarker { kind: "dot" | "icon" | "avatar" | "status", icon, actor, children } is the marker and
//   the rail down to the next event (hidden on the last one);
// TimelineContent, TimelineTitle { href }, TimelineDescription: the text column, the title (a link with
//   href; tracking steps read their status first to screen readers) and the secondary text;
// TimelineTime { value, format, placement: "inline" | "side" } is a <time> with dateTime and a full-date
//   title once hydrated; side puts it in the start column on timelines 512px wide and up;
// TimelineDetails { open, defaultOpen, onOpenChange, collapsible } is the Details toggle and its panel;
// DEFAULT_TIMELINE_LABELS holds the English strings to spread a translation over
import { Truck } from "lucide-react"
import {
  TimelineRoot, TimelineGroup, TimelineItem, TimelineMarker, TimelineContent, TimelineTitle,
  TimelineDescription, TimelineTime, TimelineDetails,
} from "@/components/ui/timeline"

export function Delivery({ tracking, sentAt }: { tracking: string; sentAt: string }) {
  return (
    <TimelineRoot variant="tracking" locale="en-US" aria-label="Delivery">
      <TimelineGroup>
        <TimelineItem status="current" index={0}>
          <TimelineMarker kind="icon" icon={<Truck />} />
          <TimelineContent>
            <TimelineTitle href={`/parcels/${tracking}`}>Handed to the courier</TimelineTitle>
            <TimelineDescription>Tracking {tracking}</TimelineDescription>
            <TimelineTime value={sentAt} />
            <TimelineDetails>Estimated delivery tomorrow, between 10 AM and 2 PM.</TimelineDetails>
          </TimelineContent>
        </TimelineItem>
      </TimelineGroup>
    </TimelineRoot>
  )
}

Props

• itemsdefault "[]"
  TimelineItemData[]

  The events: { id, title, description?, time?: Date | string | number, icon?, tone?, color?, status?: "complete" | "current" | "upcoming" | "error", actor?: { name, avatar? }, meta?, details?, href? }. Items without a time sort last and group under labels.earlier.

• variantdefault "default"
  "default" | "feed" | "tracking"

  default: markers on a line with title, description and time. feed: compact activity rows with avatars and one sentence (bold the names with <b>), grouped by day, no line. tracking: order steps with status markers and a line filled up to the current step.

• sizedefault "md"
  "sm" | "md" | "lg"

  Marker 20 / 28 / 36px (dots 8 / 10 / 12px), title 13 / 14 / 15px, and the spacing between events.

• markersdefault "auto"
  "auto" | "dot" | "icon" | "avatar"

  auto: the icon when an item has one, else the actor's avatar, else a dot (feeds prefer the avatar). The others force a kind and fall back when an item lacks it. Tracking steps always show their status.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The default marker tone: dots, tracking checks and the filled line. Each item can set its own.

• colordefault ""
  string

  Any CSS color for the markers; replaces the tone. Items with their own tone keep it.

• orderdefault "desc"
  "desc" | "asc" | "none"

  Sorts by time: desc newest first (feeds, logs), asc oldest first (tracking, where it is the default), none keeps your order. Items without a time go last.

• groupByDaydefault false
  boolean

  Day headings ("Today", "Yesterday", "Monday", then the date) in the locale. On by default in the feed variant.

• stickyGroupsdefault false
  boolean

  Day headings stick to the top of the scroll container. Set --timeline-sticky-top to clear a sticky header and --timeline-bg to the surface color behind them.

• timeFormatdefault "relative"
  "relative" | "time" | "date" | "datetime"

  relative: "5 min. ago", "yesterday", then the date after 4 weeks (under an older day heading it prints the clock time, since the heading names the day). time: 4:40 PM. date: 9/22/2026. datetime: both. Times refresh every minute.

• timePositiondefault "inline"
  "inline" | "side"

  inline: the time at the end of the title row. side: a date column on the start side (changelogs, audit logs) once the timeline itself is 512px wide; narrower (a phone, a side panel) it folds under the title. It is a container query, so it follows the space the timeline gets, not the screen.

• linedefault true
  boolean

  The connector between markers. Off by default in the feed variant.

• expandabledefault true
  boolean

  Items with details get a Details toggle. Off shows every item's details open.

• expandedKeys
  string[]

  Ids of the items whose details are open (controlled). Pair with onExpandedKeysChange.

• defaultExpandedKeysdefault "[]"
  string[]

  Ids open at first while uncontrolled.

• onExpandedKeysChange
  (keys: string[]) => void

  Fires with the open ids when a Details toggle is pressed.

• loadingdefault false
  boolean

  Skeleton events (marker and two lines) in place of the items, with aria-busy.

• skeletonCountdefault 4
  number

  How many skeleton events show while loading (1 to 12).

• hasMoredefault false
  boolean

  Shows a Show older button at the end (needs onLoadMore).

• onLoadMore
  () => (void | Promise<unknown>)

  Called by Show older. A returned promise keeps the button spinning until it settles.

• loadingMoredefault false
  boolean

  Spins the Show older button when you track the request yourself (shown while hasMore is on).

• emptyState
  ReactNode

  Replaces the default <EmptyState size="sm" preset="empty" title={labels.empty} /> when there are no items.

• error
  ReactNode

  Shows the error empty state with this message in place of the items.

• onRetry
  () => (void | Promise<unknown>)

  Adds Try again to the error state; a returned promise shows it loading.

• animateIndefault true
  boolean

  Events rise in one after another when the list appears after the page loaded (after skeletons, on a tab switch), at most 12, and new events slide in at the top. Off, new events simply appear while the rest still glide down. Server-rendered lists show at once.

• localedefault ""
  string

  Locale for times and day headings, e.g. en-US. Empty uses UIProvider's, then the browser's.

• labels
  TimelineLabelsInput

  Strings: showDetails ("Details"), hideDetails ("Hide details"), loadMore ("Show older"), earlier ("Earlier"), empty ("No activity yet"), status { complete, current, upcoming, error } read before tracking titles. English defaults in DEFAULT_TIMELINE_LABELS.

• classNames
  Partial<Record<"group" | "groupLabel" | "list" | "item" | "rail" | "marker" | "content" | "header" | "title" | "description" | "actor" | "meta" | "time" | "toggle" | "details" | "footer", string>>

  Extra classes for the inner parts.

• className
  string

  Extra classes for the root. Set --timeline-bg here when sticky headings sit on a surface.

Parts

FAQ

Used in

More React data display components