Timeline
A vertical sequence of dated events on a connected rail: order history, activity feeds, changelogs.
c2-timeline
A vertical sequence of events: an order's history, a changelog, an activity feed, a project's milestones. Each
c2-timeline-item is a marker on a rail, a label, a timestamp and whatever content sits below them, and the rail
connects each entry to the next.
layout="stacked" (the default) puts the timestamp under the label. layout="split" moves it into a column of
its own on the other side of the rail, which reads better when the dates are what the reader scans for.
The timeline tells every entry which one is last, so the connector stops there — entries added or removed later are picked up as they arrive. Entries need not be direct children: a wrapper element (or an Astro island) between the timeline and its entries is looked through.
Tone the marker with tone on an entry (primary, success, warning, danger), or put an icon in its
marker slot. Colour alone does not say what an entry means, so say it in the label too.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
layout | TimelineLayout | stacked | Where each entry's timestamp goes: under its label, or in a column of its own before the rail. |
aria-label | string | null | null | Accessible name for the list. |
Slots
| Name | Description |
|---|---|
(default) | The c2-timeline-item entries, in order. |
c2-timeline-item
One entry of a c2-timeline: a marker on the rail, a label, a timestamp and any content below them. The
connector running down to the next entry is drawn by the entry itself and stops at the last one.
Text can come from attributes for the common case (label, timestamp) or be replaced by slots when it needs
markup — a link in the label, a relative time element in the timestamp. The default slot is the entry's
content: a sentence, a card, a code block, anything.
datetime gives the timestamp a machine-readable value, so it renders as a <time datetime> element.
The host exposes what its timeline told it as custom states, never as attributes: c2-timeline-item:state(last)
on the last entry and :state(split) in a layout="split" timeline.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
label | string | — | Plain-text label. Use the label slot for markup. |
timestamp | string | — | Plain-text timestamp, shown as written. Use the timestamp slot for markup. |
datetime | string | undefined | — | Machine-readable date or time of the entry, e.g. 2026-09-29T14:30. Rendered as the timestamp's datetime. |
tone | TimelineItemTone | neutral | What the entry means, drawn as the colour of its marker. |
Slots
| Name | Description |
|---|---|
(default) | The entry's content, below the label and timestamp. |
label | Replaces the label text. |
timestamp | Replaces the timestamp text. |
marker | An icon drawn inside the marker. Grow --c2-timeline-item__marker--size to make room for it. |
CSS parts
Shadow DOM styling hooks used with ::part(name). Prefer CSS custom properties when they cover the change.
| Name | Description |
|---|---|
marker | The marker box on the rail, wrapping the assigned marker slot icon; empty, it draws a plain dot. |
connector | The line from this entry's marker down to the next entry. |
label | Container of the label text or label slot. |
timestamp | Container of the timestamp text or timestamp slot. |
content | Container of the default slot. |
CSS custom properties
Grouped by semantic target and state from --c2-<component>__<target>__<state>--<property>. Click a group to collapse it; click a name to copy it.
| Name | Type | Default | Description |
|---|---|---|---|
--c2-timeline-item--gap | pixel | 12px | Space between the rail and the text, and between the timestamp column and the rail in the split layout. |
--c2-timeline-item--padding-bottom | pixel | 24px | Space below an entry before the next one. The connector runs through it; the last entry drops it. |
--c2-timeline-item__marker--size | pixel | 12px | |
--c2-timeline-item__marker--background | color | #ffffff | |
--c2-timeline-item__marker--border | border | 2px solid #bcbcc6 | |
--c2-timeline-item__marker--border-radius | border-radius | 999px | |
--c2-timeline-item__marker--color | color | #71717a | Colour of an icon in the marker slot. |
--c2-timeline-item__marker__primary--border-color | color | rgb(2, 101, 220) | |
--c2-timeline-item__marker__primary--color | color | rgb(2, 101, 220) | |
--c2-timeline-item__marker__success--border-color | color | #15803d | |
--c2-timeline-item__marker__success--color | color | #15803d | |
--c2-timeline-item__marker__warning--border-color | color | #a16207 | |
--c2-timeline-item__marker__warning--color | color | #a16207 | |
--c2-timeline-item__marker__danger--border-color | color | #dc2626 | |
--c2-timeline-item__marker__danger--color | color | #dc2626 | |
--c2-timeline-item__connector--width | pixel | 2px | |
--c2-timeline-item__connector--background | color | #e4e4e7 | |
--c2-timeline-item__connector--gap | pixel | 4px | Space between a marker and the connector below it. |
--c2-timeline-item__label--font-size | font-size | 14px | |
--c2-timeline-item__label--font-weight | font-weight | 500 | |
--c2-timeline-item__label--line-height | pixel | 20px | Also centres the marker on the label's first line. |
--c2-timeline-item__label--color | color | #18181b | |
--c2-timeline-item__timestamp--font-size | font-size | 12px | |
--c2-timeline-item__timestamp--line-height | pixel | 20px | |
--c2-timeline-item__timestamp--color | color | #71717a | |
--c2-timeline-item__timestamp__split--width | pixel | 96px | Width of the timestamp column in the split layout. |
--c2-timeline-item__content--font-size | font-size | 14px | |
--c2-timeline-item__content--color | color | #71717a | |
--c2-timeline-item__content--margin-top | pixel | 4px | |