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.

Used inside <hy-timeline> — it only means something as part of it.

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 (filled="false")
• 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: built in

• 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.

Accessibility: your part

• State each entry's outcome in its text; the marker and its variant color are hidden from screen readers.
• In the marker slot, set decorative on a purely decorative hy-icon and give a hy-avatar its alt.

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. On by default; turn it off from markup with filled="false" (or .filled=${false} / el.filled = false). A bare filled attribute, or none at all, keeps the solid dot. Reflects as filled="" / 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 — the app's own text, in a Pages text style (slot a button or 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

CSS Custom Properties

The documented hooks. Every override hook the component reads — one per token it paints — is listed in @whitespaceux/harmony/theme-api.json, and @whitespaceux/harmony/component-bindings.json (the Harmony MCP get-bindings tool) says which part and state each one paints.

Property	Default	Description
--hy-timeline-item-rail-border-subtle-rest	var(--hy-border-subtle-rest)	Color of the connector line (the rail) when no parent hy-timeline sets --timeline-rail-color
--hy-timeline-item-stroke-md	var(--hy-stroke-md)	Hollow-marker ring width, and the rail's when no parent sets it
--hy-timeline-item-content-line-box	—	The line box of the body's first line, which the marker centers on; the small body role's by default — set it to the page's text style's line box (its line-height × font-size)