Timeline

When to use

Timeline shows the history of a record: an activity feed, a change log, the stages of a request.

When not to use

• For steps still to come: an ordered flow is shown with Stepper.
• For records to sort and filter: use DataTable.

Anatomy

1. Release stoppedNow

   A check failed.

2. Review requested27 Oct 2026, 16:05
3. Two people invited to the team26 Oct 2026, 11:20

   Invitations were sent by email.

4. Project created24 Oct 2026

LightDark

Copy code

import { Timeline, type TimelineItem, Provider } from '@bigbang/ui';

const items: TimelineItem[] = [
  { id: 'blocked', title: 'Release stopped', description: 'A check failed.', time: 'Now', tone: 'danger', icon: 'circle-alert' },
  { id: 'review', title: 'Review requested', dateTime: '2026-10-27T16:05:00', tone: 'info' },
  { id: 'invited', title: 'Two people invited to the team', description: 'Invitations were sent by email.', dateTime: '2026-10-26T11:20:00' },
  { id: 'created', title: 'Project created', dateTime: '2026-10-24', tone: 'success', icon: 'check' },
];

export default function Default() {
  return (
    <Provider locale="en-GB">
      <Timeline items={items} aria-label="History" className="max-w-lg" />
    </Provider>
  );
}

1. Marker: 24 px; a dot or an icon, coloured by tone.
2. Rail: The line joining markers; none after the last event.
3. Title and time: On one line; stacked on narrow screens.
4. Description and extra content: Optional.

Behaviour

• Events enter in turn, 50 ms apart (up to eight).
• If dateTime has a date and time both are written; a plain date shows only the date and does not shift with the time zone.
• The order is yours: put the newest first or last, and keep it the same across the product.

Guidelines

• State the outcome in the title (“Release stopped”); tone only supports it.
• Use time for relative time (“Now”) and dateTime for exact time.
• Page long histories or shorten them with “Show more”.

Content

Timeline has no text of its own; all text comes from the app.

Related components

• Stepper: Steps to come.
• StatusBadge: A single status.