OTimeline

OTimeline renders the history of an object, such as a ticket's lifecycle or an activity log, as a vertical ordered list of dated steps connected by a line, with one tinted dot per step.

Usage

Step by step

1. Import OTimeline from the ooko-ui/timeline public subpath.
2. Pass the steps to items, each with a title and optionally a meta line, a detail, and a color. Name the timeline with aria-label or aria-labelledby.
3. Set datetime to a machine-readable date or time when the meta line is a date, so it renders as a time element.

Example

The rendered example and its source come from the same Vue single-file component.

1. Ticket createdNov 9, 2026 · 10:04
2. Taken by an agentNov 10, 2026 · 14:30

   Work started on a dedicated branch.

3. MergedNov 11, 2026 · 09:12

Interactive playground

Edit the last step's title, meta line, and detail, and change its color to see the dot tint.

1. Ticket createdNov 9, 2026 · 10:04
2. Review requestedNov 11, 2026 · 09:12

   Two reviewers were assigned.

Last step color primarysecondaryinfosuccesswarningdangerneutral Title Meta Detail

Props

Prop	Type	Default	Description
items	readonly OTimelineItem[]	undefined	Steps to render, in display order.

Events

Event	Payload	Description
none	none	No custom Vue events are emitted.

Slots

Slot	Props	Description
none	none	No slots are exposed.

Related types

Type	Definition
OTimelineItem	interface OTimelineItem { /** Heading of the step. */ title: string; /** Secondary line in monospace, such as a date, a time, or an author. */ meta?: string; /** Machine-readable date or time of the step; renders the meta line as a timeelement. */ datetime?: string; /** Longer description displayed under the meta line. */ detail?: string; /** Tint of the step dot;--o-timeline-default-dot-color (neutral) when omitted. */ color?: OokoColor; }
OokoColor	type OokoColor = (typeof OOKO_COLORS)[number];

CSS custom properties

Custom property	Default	Description
--o-timeline-dot-size	0.75rem	Sets the diameter of each step dot.
--o-timeline-default-dot-color	var(--o-background-neutral-default)	Sets the dot color of steps without a color, such as var(--o-background-primary-default).
--o-timeline-line-width	2px	Sets the width of the line connecting the steps.
--o-timeline-line-color	var(--o-border-color-subtle)	Sets the color of the line connecting the steps.
--o-timeline-indent	var(--o-space-3)	Sets the space between the dot column and the step content.
--o-timeline-gap	var(--o-space-5)	Sets the space between two steps.
--o-timeline-item-gap	var(--o-space-1)	Sets the space between the title, meta, and detail lines inside a step.
--o-timeline-meta-font-family	ui-monospace, SFMono-Regular, Menlo, Consolas, monospace	Sets the font family of the meta line.

Override example

:root {
  --o-timeline-dot-size: 0.625rem;
  --o-timeline-default-dot-color: var(--o-background-primary-default);
  --o-timeline-line-color: var(--o-border-primary-light);
  --o-timeline-gap: var(--o-space-3);
  --o-timeline-item-gap: var(--o-space-2);
}

Define the same custom properties on a container instead of :root to limit an override to one part of an application.

Accessibility

• Steps render as li elements inside a native ol, so their order is announced. The ol restates role="list" because Safari drops list semantics from lists without bullets.
• Every attribute is forwarded to the ol, so aria-label, aria-labelledby, and id name and identify the timeline itself.
• With datetime, the meta line is a time element whose datetime attribute gives assistive technologies and machines an unambiguous value; the visible text stays the meta string.
• The dot and the connecting line are decorative. A step's color is never its only meaning: put the state in the title, for example "Merged" or "Rejected". In forced-colors mode the dots and the line use the system text color.
• Steps are not interactive.

Behavior and edge cases

• Steps render in the order of items; sort them before passing them, oldest or newest first.
• meta and detail are optional. With datetime but no meta, the datetime value is displayed as the meta line.
• A step without color uses --o-timeline-default-dot-color, neutral by default. OTimeline exposes no app defaults.
• The title, meta, and detail lines use relative line heights and are separated by --o-timeline-item-gap, so a long detail stays readable when the text size changes.
• Steps are keyed by their index, which is enough because they hold no state of their own.
• An empty items array renders an empty list.