Timeline

What happened, in order: an ordered list of events, each with the moment as a machine-readable <time>, who did it and what was done.

import { Timeline } from '@zitdevs/ui';

Examples

Newest first by default, whatever order the events arrive in:

1. Grace approved the request

   3 Mar 2026, 10:15

2. Grace asked for changes

   2 Mar 2026, 14:30

3. Ada opened the request

   1 Mar 2026, 09:00

Load more

<Timeline
  label="Activity"
  events={[
    {
      id: 'approved',
      time: '2026-03-03T10:15:00Z',
      timeLabel: '3 Mar 2026, 10:15',
      actor: 'Grace',
      text: 'approved the request',
      tone: 'ok',
    },
    // …
  ]}
  loadMoreHref="/requests/42?cursor=abc"
/>

Oldest first:

1. Ada opened the request

   1 Mar 2026, 09:00

2. Grace asked for changes

   2 Mar 2026, 14:30

3. Grace approved the request

   3 Mar 2026, 10:15

<Timeline label="History" events={events} order="oldest-first" />

Empty:

No activity yet

What happens to this request shows here.

<Timeline label="Activity" events={[]} empty={{ title: 'No activity yet' }} />

Props

Prop	Type	Default	Notes
label	string	required	Names the list, such as “Activity”.
events	readonly TimelineEvent[]	required	{ id, time, timeLabel, text, actor?, tone? }. Not reordered in place.
order	'newest-first' | 'oldest-first'	'newest-first'	Sorts by time. An event it cannot date keeps its place.
empty	EmptyStateProps	—	Shown when there are no events. Without it, nothing renders.
loadMoreHref	string	—	The next page of events: a link follows the list.
linkAs	LinkComponent	'a'	Renders the link, such as Next’s Link.
labels	Partial<TimelineLabels>	English	{ loadMore }. es.timeline from labels/es.
ref	Ref<HTMLDivElement>	—	The wrapper around the list and its link.
className	string	—	Placement.
anything else	<div> attributes	—

An event’s time is the instant, for machines (2026-03-01T09:00:00Z); timeLabel is the same moment written for the reader, in the page’s language and time zone. The kit formats neither. tone is one of ok, warn, danger, info and neutral, and colours the dot only.

Exported types: TimelineProps, TimelineEvent, TimelineLabels, and the label sets timelineLabels.

Accessibility

• An ordered list named by label, so the order is part of what a screen reader announces.
• Each moment is a <time datetime>; the visible text is the page’s own wording of it.
• The dot is decoration, hidden from assistive technology. The tone never carries the meaning alone: the event’s text says what happened.
• “Load more” is a link, with the kit’s focus ring.

Without JavaScript

It needs none, and renders as a Server Component. Loading more is a link to the next page of events, so each page is an address.

Theming

success, warning, accent, primary-inverse and border-strong for the dots; border-default for the line; ink, body and muted for text; primary for the link and the focus ring.