Timeline
A vertical timeline built from Timeline and TimelineItem. Items take a title, icon, timestamp (a real time element), description and any rich content such as notes, code or metrics. Six status colours cover success, warning, danger, info, pending and neutral, with status text for screen readers. A compact density uses dots for order tracking, and items can pulse as the current step or draw a dashed line toward upcoming ones.
Source
"use client";
import * as React from "react";
import type { LucideIcon } from "lucide-react";
import { cn } from "@/lib/utils";
export type TimelineStatus = "default" | "success" | "warning" | "danger" | "info" | "pending";
const MARKER: Record<TimelineStatus, string> = {
default: "bg-muted text-foreground",
success: "bg-emerald-500/12 text-emerald-700 dark:bg-emerald-400/15 dark:text-emerald-400",
warning: "bg-amber-500/15 text-amber-700 dark:bg-amber-400/15 dark:text-amber-400",
danger: "bg-rose-500/12 text-rose-700 dark:bg-rose-400/15 dark:text-rose-400",
info: "bg-sky-500/12 text-sky-700 dark:bg-sky-400/15 dark:text-sky-400",
pending: "border border-dashed border-muted-foreground/50 bg-background text-muted-foreground",
};
const DOT: Record<TimelineStatus, string> = {
default: "bg-muted-foreground",
success: "bg-emerald-500",
warning: "bg-amber-500",
danger: "bg-rose-500",
info: "bg-sky-500",
pending: "border-2 border-muted-foreground/50 bg-background",
};
const STATUS_TEXT: Partial<Record<TimelineStatus, string>> = {
success: "Completed",
warning: "Warning",
danger: "Problem",
info: "In progress",
pending: "Upcoming",
};
export interface TimelineProps extends React.OlHTMLAttributes<HTMLOListElement> {
/** "default" uses icon markers; "compact" uses small dots and tighter spacing. */
density?: "default" | "compact";
}
const DensityContext = React.createContext<"default" | "compact">("default");
export function Timeline({ density = "default", className, children, ...props }: TimelineProps) {
return (
<DensityContext.Provider value={density}>
<ol className={cn("relative", className)} {...props}>
{children}
</ol>
</DensityContext.Provider>
);
}
export interface TimelineItemProps extends Omit<React.LiHTMLAttributes<HTMLLIElement>, "title"> {
title: React.ReactNode;
status?: TimelineStatus;
icon?: LucideIcon;
/** Machine-readable time for the <time> element. */
time?: Date | string;
/** What the reader sees, e.g. "09:14" or "Yesterday". Defaults to a short date and time. */
timeLabel?: string;
description?: React.ReactNode;
/** Draw the line to the next item dashed, e.g. towards a step that has not happened yet. */
line?: "solid" | "dashed";
/** Marks the step happening now: a pulsing marker and aria-current. */
current?: boolean;
}
export function TimelineItem({
title,
status = "default",
icon: Icon,
time,
timeLabel,
description,
line = "solid",
current = false,
className,
children,
...props
}: TimelineItemProps) {
const density = React.useContext(DensityContext);
const compact = density === "compact";
const date = time ? new Date(time) : undefined;
const label =
timeLabel ?? (date ? new Intl.DateTimeFormat(undefined, { month: "short", day: "numeric", hour: "numeric", minute: "2-digit" }).format(date) : undefined);
return (
<li aria-current={current ? "step" : undefined} className={cn("group/item relative flex", compact ? "gap-3 pb-6" : "gap-4 pb-8", "last:pb-0", className)} {...props}>
<span
aria-hidden
className={cn(
"absolute bottom-0 group-last/item:hidden",
compact ? "top-5 left-[5px]" : "top-10 left-[15.5px]",
line === "dashed" ? "border-l border-dashed border-muted-foreground/40" : "w-px bg-border",
)}
/>
{compact ? (
<span aria-hidden className="relative mt-1.5 grid size-[11px] shrink-0 place-items-center">
{current && <span className={cn("absolute inset-0 rounded-full opacity-60 motion-safe:animate-ping", DOT[status])} />}
<span className={cn("relative size-[11px] rounded-full ring-4 ring-background", DOT[status])} />
</span>
) : (
<span aria-hidden className={cn("relative grid size-8 shrink-0 place-items-center rounded-full ring-4 ring-background", MARKER[status])}>
{current && <span className={cn("absolute inset-0 rounded-full opacity-40 motion-safe:animate-ping", MARKER[status])} />}
{Icon ? <Icon className="relative size-4" /> : <span className={cn("relative size-2 rounded-full", DOT[status])} />}
</span>
)}
<div className={cn("min-w-0 flex-1", compact ? "pt-0" : "pt-1.5")}>
<div className="flex flex-wrap items-baseline justify-between gap-x-3 gap-y-0.5">
<h3 className={cn("text-sm font-medium", status === "pending" && "text-muted-foreground")}>
{title}
{STATUS_TEXT[status] && <span className="sr-only">, {STATUS_TEXT[status]}</span>}
</h3>
{label && (
<time dateTime={date?.toISOString()} className="shrink-0 text-xs text-muted-foreground tabular-nums">
{label}
</time>
)}
</div>
{description && <div className="mt-1 text-sm text-muted-foreground">{description}</div>}
{children && <div className={compact ? "mt-2" : "mt-3"}>{children}</div>}
</div>
</li>
);
}
