HyTimeline

Usage examples on this page are written for Lit / plain HTML (<hy-timeline>). The same component ships as HyTimeline in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

Child components: <hy-timeline-item> — used only inside this one.

A vertical timeline rail — an ordered history feed of hy-timeline-item entries. Presentational: ordered-list semantics only, no events, no imperative API.

Marker size, rail gaps, and connector style are driven by the size / line props (not raw CSS custom properties) and propagate to the items as private --timeline-* coordination variables.

Key Features

• <ol> / <li> list semantics for accessibility
• mode: one-side (default) or alternate (zig-zag), vertical-only
• size: small | medium | large (standard Harmony size axis) — scales the marker, rail gaps, and connector via inherited CSS custom properties
• line: solid (default) / dashed connector style
• Connector stops cleanly at the last item (the parent marks it [last])

Accessibility: built in

• role="list" declared explicitly so the list semantics survive the shadow boundary (axe cannot see slotted role="listitem" items otherwise)
• Markers and connector lines are decorative; the accessible content is each item's slotted body

Accessibility: your part

• Say an entry's outcome, such as "Failed" or "Published", in its text. The marker color is not announced.

When to use

• A record of events in time order: version history, an activity log, an order's shipping.
• A project's milestones, past and planned.

Do

• Put the newest event first in an activity log, the oldest first in a sequence.
• Give every event its date or time.

When not to use

• Steps the user moves through to finish a task: hy-stepper.
• How far one operation has gone: hy-progress.
• Entries people pick or act on row by row: hy-list. Events with columns to sort: hy-table.

Examples

Version history (one-side)

<hy-timeline size="small">
  <hy-timeline-item variant="success">
    <hy-relative-time slot="opposite" date="2026-06-01"></hy-relative-time>
    Published v3
  </hy-timeline-item>
  <hy-timeline-item pending>
    <span slot="opposite">Ongoing changes</span>
    Draft
  </hy-timeline-item>
</hy-timeline>

Alternate, dashed

<hy-timeline mode="alternate" line="dashed">
  <hy-timeline-item>Step one</hy-timeline-item>
  <hy-timeline-item>Step two</hy-timeline-item>
</hy-timeline>

API

Properties

Property	Attribute	Type	Default	Description
mode	mode	'one-side' | 'alternate'	'one-side'	Rail layout mode. alternate zig-zags items across the line (vertical-only).
size	size	'small' | 'medium' | 'large'	'medium'	Size variant. Scales marker diameter, rail gaps, and connector length.
line	line	'solid' | 'dashed'	'solid'	Connector line style.
label	label	string | undefined	—	Accessible label for the list.

Slots

Slot	Description
default	hy-timeline-item elements

CSS Parts

Part	Description
base	The ordered-list element