Skip to content
comp0

comp0

Navigation

Timeline

A semantic ordered list of events in chronological order.

When to use it: Use it for history, releases, deliveries, and other sequences where order matters.

On this page
  1. Example
  2. Anatomy
  3. Step by step
  4. Keyboard
  5. Forms and accessibility
  6. API reference

Example

  1. Build completed

    All checks passed on main.

  2. Release created

    Version 0.1.0 was tagged.

  3. Deployed

    The release reached production.

Timeline.tsxtsx
import { Timeline, TimelineItem, TimelineTime } from "@comp0/react";

const events = [
  ["2026-07-14T09:15:00Z", "09:15", "Build completed", "All checks passed on main."],
  ["2026-07-14T09:22:00Z", "09:22", "Release created", "Version 0.1.0 was tagged."],
  ["2026-07-14T09:27:00Z", "09:27", "Deployed", "The release reached production."],
] as const;

export function Example() {
  return (
    <Timeline aria-label="Release history" className="w-full max-w-sm space-y-0">
      {events.map(([dateTime, time, title, description]) => (
        <TimelineItem
          key={dateTime}
          className="relative border-l border-zinc-950/15 pb-6 pl-6 last:pb-0 dark:border-white/15"
        >
          <span
            className="absolute -left-1.5 top-1.5 size-3 rounded-full border-2 border-white bg-teal-600 dark:border-zinc-950 dark:bg-teal-400"
            aria-hidden="true"
          />
          <TimelineTime
            dateTime={dateTime}
            className="text-xs font-medium text-zinc-500 dark:text-zinc-400"
          >
            {time}
          </TimelineTime>
          <h3 className="mt-1 text-sm font-semibold text-zinc-950 dark:text-zinc-50">{title}</h3>
          <p className="mt-1 text-sm text-zinc-600 dark:text-zinc-400">{description}</p>
        </TimelineItem>
      ))}
    </Timeline>
  );
}

Anatomy

Dashed frames are invisible state providers; shaded shapes own real DOM. Numbered pins match the list below.

A wireframe sketch of the assembled component. Each numbered marker matches a part in the list that follows.

  1. Timeline

    Native ordered list for a chronological sequence. Owns a DOM element.

  2. TimelineItem

    Native list item for one dated event. Owns a DOM element.

  3. TimelineTime

    Native time element carrying a machine-readable dateTime value. Owns a DOM element.

Step by step

  1. 1

    Add the main part

    Start Timeline with an aria-label that names the sequence.

  2. 2

    Add the supporting parts

    Add one TimelineItem per event and put TimelineTime beside the event summary.

  3. 3

    Make the behavior clear

    Use dateTime for the machine-readable timestamp and format the visible time for people.

    Exampletsx
    <Timeline aria-label="Release history">
  <TimelineItem>
    <TimelineTime dateTime="2026-07-14T09:15:00Z">09:15</TimelineTime>Deployed
  </TimelineItem>
</Timeline>;

Keyboard

Forms and accessibility

Timeline is descriptive content and does not create form values.

Accessibility checklist

  • Give the ordered list a name when the surrounding heading does not already do so.
  • Use a machine-readable dateTime value on TimelineTime and keep its visible text understandable in context.
  • Do not use the visual line or dots as the only way to convey order; the native ordered list supplies that relationship.

API reference

Importtsx
import { Timeline, TimelineItem, TimelineTime } from "@comp0/react";

Timeline

DOM element

Native ordered list for a chronological sequence.

PropTypeDescription
aria-labelstringNames the sequence when a nearby heading does not.
aria-labelledbystringNames the sequence when a nearby heading does not.

TimelineItem

DOM element

Native list item for one dated event.

TimelineTime

DOM element

Native time element carrying a machine-readable dateTime value.

PropTypeDescription
dateTimestringMachine-readable ISO date or time for the visible label.

Keep exploring