What is Timeline?

A timeline lays out events along a line so their order in time is visible: a project's history, an order's journey from placed to delivered, an audit log of who changed what, a release changelog, a company's milestones. Each entry has a marker on the line, a time, a title and often a line of detail. The line is the point. It tells the reader that these items belong to one sequence and that reading down means moving through time.

Design decisions

• Direction. Feeds and logs run newest first, because the latest event is what people came for. Histories, processes and roadmaps run oldest first, because the story reads forward.
• Time labels. Use relative times ("2 hours ago") for recent events and absolute dates for older ones, and expose the full timestamp on hover or focus. Group entries under day headings when a day has many events.
• Markers. A dot is enough. Icons or avatars on the markers help when the actor or the kind of event matters, such as a deploy versus a comment.
• Density. Keep each entry to a title and one line. Long content belongs behind an expand control or on a detail page.
• Not for steps. A list of steps the user must complete is a stepper, with a current step and a way forward.

Accessibility

Markup matters more than it seems. Use an ordered list, since order is the meaning, and put the time in a time element with a machine-readable datetime attribute so assistive technology and crawlers can read the real date behind "yesterday". Markers and the line are decorative; draw them with CSS or mark them aria-hidden. If entries have headings, use real heading elements so screen reader users can jump between events. For feeds that grow, announce new entries through a polite live region or let the user load them, rather than reshuffling the list under them.

How to build one in React

MiniDev's Timeline renders an ordered list on a hairline with a marker, a title, a time and a description per entry. It does not sort; pass entries in the order they should read:

import { Timeline, type TimelineItem } from "@/components/ui/timeline"

const EVENTS: TimelineItem[] = [
  { title: "Invoice INV-2041 paid", description: "$12,400 via bank transfer", time: "09:41" },
  { title: "Reminder sent", description: "To billing@northwind.com", time: "Mar 10" },
  { title: "Invoice issued", description: "By Maya Chen", time: "Mar 1" },
]

export function InvoiceHistory() {
  return <Timeline items={EVENTS} />
}

RelativeTime formats "3h ago" while carrying the exact ISO timestamp for machines, ActivityFeed adds actors and avatars, and AuditTrail is the bordered, newest-first version for audit logs. Timelines usually sit in a dashboard detail pane, loading older entries with a Load more button rather than infinite scroll.