Timeline

Data Display

Chronological events with status, timestamps, and compact/card layouts.

Card layoutCompact layoutComplete, current and pending states

Responsive viewport — resize the window to explore. Direction and density apply only to this preview. Theme applies to the docs too.

timeline.tsx

"use client";

import { Timeline } from "@/components/ui/timeline";
import { Button } from "@dashboardpack/core/components/ui/button";
import { useState } from "react";

export default function TimelineExample() {
  const [compact, setCompact] = useState(false);
  return (
    <div className="w-full max-w-md space-y-4">
      <Button size="sm" variant="outline" onClick={() => setCompact(!compact)}>
        {compact ? "Show cards" : "Compact view"}
      </Button>
      <Timeline
        compact={compact}
        events={[
          {
            id: "created",
            title: "Order received",
            description: "Order #APX-1024 was created.",
            time: "09:00",
            dateTime: "2026-10-27T09:00:00Z",
            status: "complete",
          },
          {
            id: "packed",
            title: "Preparing shipment",
            description: "Your items are being packed.",
            time: "10:15",
            dateTime: "2026-10-27T10:15:00Z",
            status: "current",
          },
          {
            id: "delivery",
            title: "Out for delivery",
            description: "We will notify you when your order is on its way.",
            status: "pending",
          },
        ]}
      />
    </div>
  );
}

Usage

Provide events in the order you want them displayed. time is the visible text and dateTime is an optional machine-readable ISO timestamp. Use compact for dense activity feeds or cards for richer descriptions.

Import

import { Timeline } from "@/components/ui/timeline";

Shipped as editable source in src/components/ui/timeline.tsx in both apps. Copy the implementation below when moving it to another project. Copy the complete example from Source code for all imports and state. Add "use client" when using hooks or event handlers. See installation and theming for project setup.

Component source

The complete implementation is included in both apps. It uses the React, Radix, Lucide, and shared-core dependencies already installed in Apex. Keep your project’s semantic theme tokens when reusing it.

src/components/ui/timeline.tsx

import type { ReactNode } from "react";
import { Check, Circle } from "lucide-react";
import { cn } from "@dashboardpack/core/lib/utils";
export interface TimelineEvent {
  id: string;
  title: string;
  description?: ReactNode;
  time?: string;
  dateTime?: string;
  status?: "complete" | "current" | "pending";
  icon?: ReactNode;
}
export function Timeline({
  events,
  compact = false,
  label = "Activity timeline",
  className,
}: {
  events: TimelineEvent[];
  compact?: boolean;
  label?: string;
  className?: string;
}) {
  return (
    <ol aria-label={label} className={cn("space-y-0", className)}>
      {events.map((event, index) => (
        <li
          key={event.id}
          className={cn(
            "relative ps-10",
            index !== events.length - 1 && "pb-6",
          )}
        >
          <span
            aria-hidden
            className={cn(
              "absolute start-0 top-0 flex size-7 items-center justify-center rounded-full border bg-background [&_svg]:size-3.5",
              event.status === "pending"
                ? "text-muted-foreground"
                : "border-primary/30 text-primary",
            )}
          >
            {event.icon ??
              (event.status === "complete" ? (
                <Check />
              ) : (
                <Circle
                  className={
                    event.status === "current" ? "fill-primary/20" : undefined
                  }
                />
              ))}
          </span>
          {index !== events.length - 1 && (
            <span
              aria-hidden
              className="absolute start-[13px] top-8 h-[calc(100%-2rem)] border-s"
            />
          )}
          <div
            className={cn(
              "space-y-1",
              !compact && "rounded-lg border bg-card p-3",
            )}
          >
            <div className="flex flex-wrap items-baseline justify-between gap-2">
              <h3 className="text-sm font-medium">{event.title}</h3>
              {event.time && (
                <time
                  dateTime={event.dateTime}
                  className="text-xs text-muted-foreground"
                >
                  {event.time}
                </time>
              )}
            </div>
            {event.status && <span className="sr-only">{event.status}</span>}
            {event.description && (
              <div className="text-sm leading-relaxed text-muted-foreground">
                {event.description}
              </div>
            )}
          </div>
        </li>
      ))}
    </ol>
  );
}

API reference

Common props and defaults. Slot-specific props are named below; native elements also accept their standard HTML attributes. The component TypeScript definitions are the complete type reference.

Timeline props
Prop	Type / Default	Description
events	`TimelineEvent[]` Default: required	Ids, titles, descriptions, timestamps, statuses, and optional icons.
compact	`boolean` Default: false	Use a dense layout without event cards.
label	`string` Default: Activity timeline	Accessible ordered-list name.
className	`string` Default: —	Extend the list container.

Build with these too

Stepper DescriptionList