Timeline

A vertical timeline component for displaying chronological events with status indicators, custom icons, and timestamps.

All Statuses

Each TimelineItem accepts a status of complete, active, or upcoming (default).

Design

Wireframes and prototypes approved.

Jan 10, 2024

Development

Building the feature.

Jan 20, 2024

Launch

Ship to production.

Custom Icon

Use TimelineIcon to replace the default dot with any content.

✓

Completed Step

This step is done.

→

Active Step

Currently in progress.

○

Upcoming Step

Not yet started.

With Timestamps

TimelineTimestamp renders a <time> element. Pass a machine-readable dateTime for semantic correctness.

Repository created

March 1, 2024

First commit pushed

March 5, 2024

Beta release

April 1, 2024

Installation

npx visor add timeline

This copies two files into your project:

components/ui/timeline/timeline.tsx — the component
components/ui/timeline/timeline.module.css — the styles

Usage

import {
  Timeline,
  TimelineItem,
  TimelineContent,
  TimelineTitle,
  TimelineDescription,
} from '@/components/ui/timeline/timeline';

export default function Example() {
  return (
    <Timeline>
      <TimelineItem status="complete">
        <TimelineContent>
          <TimelineTitle>Order placed</TimelineTitle>
          <TimelineDescription>Your order has been confirmed.</TimelineDescription>
        </TimelineContent>
      </TimelineItem>
      <TimelineItem status="active">
        <TimelineContent>
          <TimelineTitle>In transit</TimelineTitle>
          <TimelineDescription>Package is on its way.</TimelineDescription>
        </TimelineContent>
      </TimelineItem>
      <TimelineItem>
        <TimelineContent>
          <TimelineTitle>Delivered</TimelineTitle>
        </TimelineContent>
      </TimelineItem>
    </Timeline>
  );
}

API Reference

TimelineItemProps

Prop	Type	Default	Description
`status`	`'complete' \| 'active' \| 'upcoming'`	`'upcoming'`	Status of a TimelineItem, controls dot and connector styling.
`dateTime`	`string`	—	Machine-readable date for TimelineTimestamp (HTML time element).
`className`	`string`	—	Additional CSS class names to merge onto the element.

The container and all sub-components accept standard HTML <div> attributes. TimelineTimestamp renders a <time> element and accepts a dateTime prop.

Sub-components

Component	Element	Purpose
`Timeline`	`<div>`	Container
`TimelineItem`	`<div>`	Item wrapper with status
`TimelineIcon`	`<div>`	Optional custom icon slot
`TimelineContent`	`<div>`	Content wrapper
`TimelineTitle`	`<div>`	Event title
`TimelineDescription`	`<p>`	Event description
`TimelineTimestamp`	`<time>`	Semantic timestamp

Accessibility

Use TimelineTimestamp with a dateTime attribute in ISO 8601 format (YYYY-MM-DD or YYYY-MM-DDTHH:mm:ss) for machine-readable dates that screen readers and parsers understand.
The status prop maps to a data-status attribute which drives visual styling — no ARIA role is applied automatically. For critical status changes (e.g., order tracking), consider adding aria-label to TimelineItem describing the status.
If icons in TimelineIcon are purely decorative, ensure they have aria-hidden="true".
Wrap the entire Timeline in a <section> with an aria-label when it represents a named region of the page.

Timeline

On this page