Timeline

A vertical activity feed grouped by day, newest first, with pinned day labels, expandable rows and new updates that slide in at the top.

When to use

• Project history, audit logs, deploy streams: anywhere order and recency matter.
• When some events carry extra detail people may want to open in place.
• Use SortableDataTable when people need to sort or compare entries, and CommentThread for a discussion.

Usage

import { Timeline } from "@/components/iris/timeline/timeline";

h(Timeline, {
  label: "CapyDB project activity",
  now: Date.now(),
  maxHeight: 420,
  events: [
    {
      id: "e1",
      at: "2026-10-22T15:18:00Z",
      actor: "Stelios Antoniou",
      title: "created preview database pr-142 from shop",
      meta: "Clone · 1.0 GiB",
      icon: h(BranchIcon),
      detail: h("p", null, "The preview expires in 18 h."),
    },
    {
      id: "e2",
      at: "2026-10-22T14:50:00Z",
      title: "Backup verified for notdocs",
      meta: "Nightly · 3.1 GiB",
      tone: "success",
      icon: h(CheckIcon),
    },
  ],
});

Props

Prop	Type	Default	Description
events	TimelineEvent[]	— (required)	Any order; newest shows first. { id; at: ISO string | epoch ms; actor?; title; meta?; detail?; avatar?: url; icon?; tone?: "neutral" | "success" | "danger" }.
now	number	— (required)	Reference time (epoch ms) for relative labels and day groups. Pass a ticking clock to keep labels fresh.
label	string	— (required)	Accessible name for the feed.
timeZone	string	"UTC"	Time zone for day groups and clock times. Fixed by default so server and client agree.
locale	string	"en-US"	Formatting locale.
maxHeight	number | string	—	Makes the feed scroll inside this height; without it the feed grows with the page.
scrollToNew	boolean	true	Scroll back to the top when a new update arrives while scrolled down.
defaultExpanded	string[]	[]	Event ids open on first render.
headingLevel	2 | 3 | 4 | 5 | 6	3	Heading level of the day labels.

Notes

• Arrow keys move between rows; Enter or Space expands a row with detail. Rows without detail are not interactive.
• actor is shown first in the foreground colour and title completes the sentence ("Stelios created …").
• The marker shows avatar (an image URL) or else icon; there is no initials fallback, so give person events an icon or a portrait. tone tints system-event markers; always state the outcome in the title too.
• The connecting line draws itself as rows come into view; under reduced motion everything appears at once.