Timeline

Accessible, unstyled timeline built on a native ordered list with progress states.


Package	`@vizejs/ui/timeline`
Maturity	stable
Own the source	`vize lib pull timeline`
Requires	collection, context, id
Aliases	timeline, activity feed, history, event log, progress steps
Covers	HTML ordered list, HTML time element, MUI Timeline, Mantine Timeline

Usage

import { Timeline, TimelineRoot, TimelineConnector, TimelineContent, TimelineIndicator, TimelineItem, TimelineTime } from "@vizejs/ui/timeline";

Or copy the source into your project with vize lib pull timeline (see Source Distribution).

API

`Timeline`

Source: src/families/data/timeline/timeline-root.vue

Props

Prop	Type	Default	Description
`value`	`string \| null`	`null`	Value of the current item. Earlier items become `complete`, later ones `upcoming`.
`orientation`	`TimelineOrientation`	`"vertical"`	Layout axis exposed to styles.
`reversed`	`boolean`	`false`	List items newest first with the native `reversed` ordered-list semantics.
`ariaLabel`	`string`	`undefined`	Accessible name for the list.
`ariaLabelledby`	`string`	`undefined`	Space-separated ids that label the list.

Slots

Slot	Slot props	Description
`default`	`TimelineSlotState`	TimelineItem children. Receives the current value, axis, and item count.

Exposed

Member	Type	Description
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.
`value`	—
`values`	—

`TimelineRoot`

Source: src/families/data/timeline/timeline-root.vue

Props

Prop	Type	Default	Description
`value`	`string \| null`	`null`	Value of the current item. Earlier items become `complete`, later ones `upcoming`.
`orientation`	`TimelineOrientation`	`"vertical"`	Layout axis exposed to styles.
`reversed`	`boolean`	`false`	List items newest first with the native `reversed` ordered-list semantics.
`ariaLabel`	`string`	`undefined`	Accessible name for the list.
`ariaLabelledby`	`string`	`undefined`	Space-separated ids that label the list.

Slots

Slot	Slot props	Description
`default`	`TimelineSlotState`	TimelineItem children. Receives the current value, axis, and item count.

Exposed

Member	Type	Description
`element`	`HTMLOListElement \| null`	Rendered ordered list.
`value`	`string \| null`	Current item value.
`values`	`readonly string[]`	Registered item values in document order.

`TimelineConnector`

Source: src/families/data/timeline/timeline-connector.vue

Slots

Slot	Slot props	Description
`default`	`TimelineItemSlotState`	Optional decorative content. Receives the owning item's progress state.

`TimelineContent`

Source: src/families/data/timeline/timeline-content.vue

Slots

Slot	Slot props	Description
`default`	`TimelineItemSlotState`	Item body such as a title and description. Receives the owning item's progress state.

`TimelineIndicator`

Source: src/families/data/timeline/timeline-indicator.vue

Slots

Slot	Slot props	Description
`default`	`TimelineItemSlotState`	Optional decorative content. Receives the owning item's progress state.

`TimelineItem`

Source: src/families/data/timeline/timeline-item.vue

Props

Prop	Type	Default	Description
`value`	`string \| null`	`null`	Item value compared with the root `value` to derive progress.
`status`	`TimelineItemStatus`	`undefined`	Explicit progress status that overrides the derived one.

Slots

Slot	Slot props	Description
`default`	`TimelineItemSlotState`	Item content. Receives the index, progress status, and whether this is the last item.

Exposed

Member	Type	Description
`value`	`string \| null`	Item value, or `null` for untracked items.
`index`	`number`	Zero-based position in document order.
`status`	`TimelineItemStatus \| null`	Progress status: explicit, derived from the root value, or `null`.
`last`	`boolean`	Whether this is the last item, which usually omits its connector.
`element`	`HTMLLIElement \| null`	Rendered list item.

`TimelineTime`

Source: src/families/data/timeline/timeline-time.vue

Props

Prop	Type	Default	Description
`datetime` (required)	`string \| Date`	`required`	Machine-readable date, time, or duration for the native `<time>` element.

Slots

Slot	Slot props	Description
`default`	`{ /** Machine-readable datetime rendered into the datetime attribute. */ readonly datetime: string; }`	Human-readable, consumer-formatted time text. Receives the ISO datetime string.

Behavior

Normative state x input -> outcome table for timeline-root.vue, timeline-item.vue, timeline-indicator.vue, timeline-connector.vue, timeline-content.vue, and timeline-time.vue (@vizejs/ui/timeline). Every row is proven by the named test in timeline.test.ts or timeline-ssr.test.ts; compile-only guarantees live in timeline.types.test-d.ts.

A timeline is a native <ol> of <li> items, so assistive technology already announces item count and position. The current item carries aria-current="step"; indicators and connectors are aria-hidden decoration; TimelineTime renders a native <time datetime>.

ID	State	Input	Outcome	Evidence
L1	untracked	render	labelled `ol`/`li` structure, hidden decorative parts, last-item marker, native `<time>`	`renders a labelled ordered list with decorative parts and native time`
L2	root `value`	render, value change	items before the value are `complete`, the match is `current`, later ones `upcoming`	`derives complete, current, and upcoming states from the root value`
L3	explicit item `status`	render	the explicit status wins over derived progress	`explicit item status overrides derived progress`
L4	`reversed`, `horizontal`	render	native `reversed` numbering and orientation data attributes	`reversed and horizontal timelines expose native and data semantics`
L5	conditional items, `Date`	insert item, render time	inserted items join document order; `Date` values serialize to deterministic ISO strings	`items added later join document order and Date values serialize to ISO`
L6	missing provider	setup	item parts fail closed with the shared context diagnostic	`compound parts require matching providers`
L7	SSR and hydration	isolated render/mount	progress is derived during the single server pass and hydrates without warnings	`timeline-ssr.test.ts`

Items render before later siblings register, so during server rendering an item seen before the current value is treated as complete; after mount a value that matches no item clears every derived status.