data-display / stable

Timeline

Compact activity events with day groups, small semantic markers, actor sentences, an optional right-aligned value per row and exact timestamps on focus or hover.

LIVE PREVIEW

Loading preview…

When to use

Status changes, audit logs and activity dialogs.
A history where each row carries one signed value: pass trailing, plus timeZone and timeFormat="time" for after-the-fact review.
Use TimelineItem for events interleaved with comments.

Consider an alternative

Editable conversations: use RecordCommentStream.
Readiness gates: use Callout with Checklist.

Import

import { Timeline } from '@revido-llc/kit';

Keyboard interaction

Tab — focus timestamps and event actions.
Enter / Space — show more events.

Props

Props documented by the Kit. Refer to the TypeScript types for the complete interface, including inherited props.


items (required)	readonly TimelineEvent[]	—
aria-label	string	—
className	string	—
density	"default" \| "compact"	"compact"
earlierLabel	string	"Earlier"	Heading of the group for events whose `createdAt` is not a valid date. Pass a translation for non-English UIs.
limit	number	5
now	Date	new Date()
showLessLabel	string	"Show less"	Text of the button that collapses the list back to `limit` events. Pass a translation for non-English UIs.
showMoreLabel	((hidden: number) => string)	(hidden) => `Show ${hidden} more`	Text of the button that reveals the events beyond `limit`, given how many are hidden. Pass a translation for non-English UIs.
timeFormat	"relative" \| "time"	"relative"	"relative" ("3 hours ago") or "time" (time of day; the day heading already carries the date, for histories reviewed after the fact).
timeUnavailableLabel	string	"Time unavailable"	Shown instead of the time for an event whose `createdAt` is not a valid date. Passed to every item.
timeZone	string	the browser zone	IANA zone for day groups, "Today"/"Yesterday" (named in the Kit locale) and absolute times.

Related exports

TimelineItem

Examples

Markers and tones

<Timeline items={events} />

Collapsed history

<Timeline items={events} limit={1} />

Dated values per row

One right-aligned value per row; day groups and times in an explicit zone.

<Timeline items={entries} limit={entries.length} timeZone="Europe/Amsterdam" timeFormat="time" />

Literal history

Pass dated event objects directly; now defaults to the current time.

<Timeline items={[{ id: "created", actor: "Ada", action: "created this item", createdAt: "2026-10-12T10:00:00Z", leading: { kind: "avatar", name: "Ada" } }]} />

Literal event

Use as=div when embedding an event outside a list.

<TimelineItem as="div" event={{ id: "created", actor: "Ada", action: "created this item", createdAt: "2026-10-12T10:00:00Z" }} />

Dutch labels (nl-NL)

Day titles and times follow the Kit locale (KitProvider locale). The strings the Kit cannot translate for you are props: pass each in your language.

<Timeline items={events} limit={1}
  earlierLabel="Eerder"
  showMoreLabel={(hidden) => `Toon nog ${hidden}`}
  showLessLabel="Toon minder"
  timeUnavailableLabel="Tijd onbekend" />