Timeline
Displays a series of event nodes in chronological order.
Breaking change: node color semantics upgrade (v2.4)
color="green | red | gray" has been replaced by the semantic color enum type: green → success, red → danger, gray → neutral. The three legacy color values are still mapped for compatibility in this version (scheduled for removal — please migrate soon); other values no longer take effect. For arbitrary custom colors, do not use an attribute — override the CSS variable --oas-timeline-dot-color in one line (e.g. style="--oas-timeline-dot-color: var(--oas-color-warning)").
Basic Usage
Basic timeline
Project kickoff; goals and scope defined.
Core components developed; unit tests pass.
Fixed production issues and ran regression.
Docs site launched and published.
Semantic Colors (type)
type provides the node semantic color enum: primary (default) / success / warning / danger / info / neutral (gray = archived), aligned with the library semantic color tokens (dark variants included). For arbitrary colors use the --oas-timeline-dot-color CSS variable.
Node semantic colors and arbitrary color
Default theme color (primary)
success: completed
warning: attention needed
danger: failure / alert
info: general information
neutral: archived (formerly gray)
Arbitrary color via the --oas-timeline-dot-color variable
Legacy color mapping (to be removed, migrate to type)
color="green" → success
color="red" → danger
color="gray" → neutral
Node Variant (variant)
variant="outlined" renders the node as a hollow outlined dot (default filled solid), composable with type.
outlined nodes
filled solid (default)
outlined: pending review
outlined + warning
Custom Nodes (dot slot / icon attribute)
Nodes can be fully customized with slot="dot" (any content), or rendered quickly with the icon attribute using library icons (color follows type).
icon attribute nodes
Build package uploaded
Pre-release checks passed
Canary smoke test failed
Re-release after fix
dot slot custom nodes
Step one: submit the request
Step two: review approved
Dot size and color customization
Small dot (--oas-timeline-dot-size: 6px)
Default size (10px)
Large dot (16px)
Custom color (--oas-timeline-dot-color: #7c3aed)
Title Structure (title slot)
slot="title" renders an emphasized title line, separated from the body (default slot) — great for release records and changelogs.
Title + body
Added data-display components; see the release notes.
Improved the dark theme and accessibility.
Pending and Loading (pending / loading)
pending marks an in-progress tail node: hollow dot + dashed connector + pulse animation, showing "Coming soon" when empty. loading marks a single loading node (spinner ring), with aria-busy synced on the content area.
Pending tail node + loading node
v1.4.0 requirements review completed.
Core features developed; unit tests pass.
Running regression tests…
Setting pending on an oas-timeline-item renders that node as a hollow dot with a dashed connector, meaning "in progress / coming soon"; a node without content shows the "Coming soon" text by default.
Reverse Order (reverse)
reverse renders visually in reverse (latest on top) while keeping the DOM order stable (screen-reader and focus order unchanged); commonly combined with pending for "latest in-progress activity".
reverse order
The earliest commit
Intermediate milestone
Most recent release (visually on top)
Horizontal Timeline (direction)
direction="horizontal" lays the axis horizontally with items in a row (great for milestones and release pipelines). In horizontal mode, mode maps as: left content below the axis (default), right content above the axis, alternate alternating above/below.
Horizontal timeline
Kickoff
Core dev
Integration
Release
Horizontal + alternate
Kickoff
Core dev
Integration
Release
Alternate Mode and Opposite Content (mode / opposite)
mode controls the content position relative to the axis: left (default, axis on the left) / right (axis on the right) / alternate (axis centered, content alternating left/right, first item on the left). slot="opposite" places content on the opposite side of the axis in alternate mode (e.g. time on the outer side, summary on the inner side).
mode=right
Axis on the right, content on the left
A mirrored layout for RTL contexts
mode=alternate + opposite slot
First beta
Public launch
Performance tuning
The opposite content channel only shows in alternate mode; in single-side modes (left/right) slot="opposite" is hidden.
Item Click (oas-click)
Timeline items support a click event oas-click (detail carries { index }, bubbles + composed) — great for log streams where clicking an item opens details.
Click items
Order #1024 paid
Order #1024 shipped from warehouse
Order #1024 transit delay
Rich Content and Interaction
Node content is distributed in place from the host DOM, so buttons and links inside keep their event handlers (previously the clone-based rendering lost host listeners — fixed).
Rich content nodes (button events work)
v1.2.0 released
Added data-display components.
v1.3.0 released
Improved the dark theme and accessibility.
Font Size
Font size follows the outer context (inherited) by default; override with the CSS variable --oas-timeline-font (e.g. 18px). Node and connector sizing hooks: --oas-timeline-dot-size / connector width follows the size.
Size Presets
size offers five presets: xs / small / medium (default) / large / xl (sm/md/lg aliases are equivalent; invalid values fall back to medium). Each preset scales the dot diameter (6/8/10/12/16px — the connector start/end follows the dot size) and the font size (--oas-font-size-* tokens; medium follows the outer font size).
size presets
API
oas-timeline
Attributes
| Attribute | Description | Type | Default |
|---|---|---|---|
direction | Axis direction: vertical (default) / horizontal (items laid out in a row) | string | — |
mode | Content position relative to the axis: left (default, axis on the left) / right (axis on the right) / alternate (axis centered, content alternates sides, first item on the left); in horizontal mode maps to below/above/alternating | string | — |
reverse | Visual reverse order (DOM order unchanged); pairs with pending for "newest first" | boolean | — |
size | Five presets scaling the dot diameter (6/8/10/12/16px, connector follows) and font-size tokens | string | medium |
Slots
| Name | Description |
|---|---|
| default | Timeline nodes (oas-timeline-item) |
CSS Variables
| CSS Variable | Default |
|---|---|
--oas-timeline-font | inherit |
oas-timeline-item
Attributes
| Attribute | Description | Type | Default |
|---|---|---|---|
color | [Migration compat] Legacy node color: green→success, red→danger, gray→neutral; will be removed. Use type for new code; arbitrary colors via --oas-timeline-dot-color | string | — |
icon | Node icon (library oas-icon name), colored by type; slot="dot" wins | string | — |
loading | Per-node loading: the dot becomes a spinner, content area syncs aria-busy | boolean | — |
pending | In-progress node: hollow dot + dashed connector + pulse; shows "Coming soon" when empty | boolean | — |
time | Time text of the node | string | — |
type | Semantic node color: primary (default) / success / warning / danger / info / neutral | string | — |
variant | Node variant: filled (default solid) / outlined (hollow stroke) | string | — |
Events
| Event | Description |
|---|---|
oas-click | Item click (content area); detail carries |
Slots
| Name | Description |
|---|---|
| default | Node body content |
dot | Custom node (any content replaces the dot) |
opposite | Opposite-side content (only shown in mode=alternate) |
title | Title emphasis line (separated from the body) |
CSS Variables
| CSS Variable | Default |
|---|---|
--oas-timeline-dot-color | var(--dot-color, var(--oas-color-primary)) |
--oas-timeline-dot-size | 10px |
--oas-timeline-font | inherit |