HyTimelineItem

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

A single entry within an hy-timeline. Presentational by design — it renders a marker on the rail, optional other-rail content, and the entry body. It is NOT a selection model: there are no events, no roving tabindex, no keyboard navigation. For a per-item action, slot an hy-button/link into the default slot.

Key Features

• <li> list semantics (the parent hy-timeline is the <ol>)
• variant-colored marker dot, token-constrained (no arbitrary color)
• filled solid dot vs hollow ring
• pending "ongoing" state — an hy-spinner replaces the dot
• marker-align centers the dot on the body's first line (default) or the whole content row (center, for button/badge control rows)
• marker slot for a custom dot (icon / avatar / number)
• opposite slot for other-rail content (timestamp / label)

Accessibility

• role="listitem" on the host (reflected for SSR)
• The marker dot, pending spinner, and connector line are decorative (aria-hidden); the accessible content is the slotted body. A custom marker slot keeps its own semantics.

Sizing / line / layout

• size, line, and mode are owned by the parent hy-timeline and reach the item via inherited CSS custom properties (--timeline-*). The item has no size prop of its own.

Examples

Within a timeline

<hy-timeline>
  <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>

Custom marker

<hy-timeline-item>
  <hy-icon slot="marker" name="check"></hy-icon>
  Reviewed
</hy-timeline-item>

API

Properties

Property	Attribute	Type	Default	Description
variant	variant	'neutral' | 'brand' | 'success' | 'warning' | 'danger'	'neutral'	Semantic marker color. Token-constrained — no arbitrary color.
filled	filled	boolean	true	Solid dot (default) vs hollow ring (filled={false}).
pending	pending	boolean	false	"Ongoing" — renders an hy-spinner in place of the dot. Intended for the last item.
markerAlign	marker-align	'first-line' | 'center'	'first-line'	Marker vertical alignment against the entry body. - first-line (default): center the marker on the body's first text line — correct for text entries (including multi-line, where the dot should sit next to the first line, not the paragraph's middle). - center: center the marker on the whole content row — correct when the body is a control row (buttons/badges) taller than one text line.

Slots

Slot	Description
default	The entry body (text / markup; slot a button/link for an action)
marker	Custom marker dot (icon, avatar, number). Overrides the default variant dot.
opposite	Other-rail content (timestamp via hy-relative-time, label)

CSS Parts

Part	Description
opposite	The opposite-rail cell
marker	The marker-rail cell (carries the connector line)
content	The entry body cell