Timeline
An ordered sequence of events with per-item state, connectors, titles, timestamps, and vertical or horizontal flow.
Implementation previewEvery example. In one place.
Explore every named example, including states, compositions, and theme variants.
Example source
packages/design-system/src/components/status/Timeline/Timeline.stories.tsxExport PlaygroundImplementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.
Stories + source JSON ↗Local specification source status: preview. Implementation preview pending sign-off.
An ordered sequence of events with per-item state, connectors, titles, timestamps, and vertical or horizontal flow.
Implementation API 1 entry point · source-derived preview
Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.
import { Timeline } from '@cloakedinc/design-system';TimelineTimelineProps
packages/design-system/src/components/status/Timeline/Timeline.tsx:48
| Prop | Type | Presence | Notes |
|---|---|---|---|
items | readonly TimelineItem[] | Required | Events in render order; each `id` keys its row and seeds its test id. |
ariaLabel | string | undefined | Optional | Names the ordered list for assistive tech. |
orientation | TimelineOrientation | undefined | Optional | Direction used to lay out events. Defaults to `'vertical'`.Source default: 'vertical' |
className | string | undefined | Optional | |
style | React.CSSProperties | undefined | Optional | |
testId | string | undefined | Optional | Optional test selector. Each event derives `${testId}-${item.id}`. |
Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.
Overview
An ordered sequence of events or steps over time, connected by a line and driven by a per-item
state (complete / active / upcoming).
When to use
Reach for Timeline when the stages themselves carry content — a removal journey, an activity log,
a multi-day process — and each event has a title, optional description, and timestamp worth showing.
- Only showing position in a short flow ("step 2 of 4") with no per-event detail? Use
Progress.Steps, the active stepper. - An unordered set of rows with no temporal sequence or connector line? Use
List.
Component specification
$schema
../../../specs/component-spec.schema.jsonParts
- Id
- root
- Label
- Root
- Description
- Ordered list that flows events vertically or horizontally.
- Required
- true
- Id
- item
- Label
- Item
- Description
- One event row pairing a marker column with content.
- Id
- node
- Label
- Node
- Description
- State marker showing a check, custom icon, or active dot.
- Id
- connector
- Label
- Connector
- Description
- Line joining adjacent events.
- Id
- content
- Label
- Content
- Description
- Title, timestamp, and optional description.
Allowed Design Choices
- Variants
- Events
- Label
- Events
- Description
- The single ordered-event treatment.
- Sizes
- Orientations
- Vertical
- Label
- Vertical
- Description
- Events stack top to bottom.
- Horizontal
- Label
- Horizontal
- Description
- Events flow left to right and scroll on overflow.
Variants
- Id
- events
- Label
- Events
- Description
- Ordered event sequence with connectors.
- Platforms
- ios
- android
- web
Sizes
None specifiedMeasurements
- Id
- item-gap
- Label
- Marker and content gap
- Kind
- exact
- Token
- --cds-space-12
- Value
- 12
- Unit
- px
- Applies To
- item
- Id
- node-size
- Label
- Node size
- Kind
- exact
- Token
- --cds-size-24
- Value
- 24
- Unit
- px
- Applies To
- node
- Id
- content-inset
- Label
- Content bottom inset
- Kind
- exact
- Token
- --cds-space-20
- Value
- 20
- Unit
- px
- Applies To
- content
Layout
- Alignment
- The marker column aligns with the top of each event's content.
- Flow
- Vertical stacks a node-plus-content grid per event; horizontal lays events in a scrolling row.
- Notes
- Use Progress.Steps when you only need position in a short flow without event detail.
Typography And Color
- Typography
- Label
- Title
- Description
- Uses the body ramp (body-small when horizontal).
- Token
- --cds-type-body-size
- Label
- Timestamp and description
- Description
- Use the body-small ramp.
- Token
- --cds-type-body-small-size
- Colors
- Label
- Complete
- Description
- Complete nodes and connectors use the brand accent.
- Token
- --cds-brand
- Label
- Active
- Description
- Active nodes use the subtle brand wash.
- Token
- --cds-brand-subtle
- Label
- Upcoming
- Description
- Upcoming nodes outline with the divider color.
- Token
- --cds-divider
States
- Id
- complete
- Label
- Complete
- Description
- Finished event with a filled node and check.
- Id
- active
- Label
- Active
- Description
- Current event, marked aria-current=step.
- Id
- upcoming
- Label
- Upcoming
- Description
- Future event with an outlined node.
Behavior
- Label
- Per-item state
- Description
- Each event declares complete, active, or upcoming; the active event is aria-current.
- Label
- Connectors
- Description
- A connector joins each event to the next; the last event omits it.
Accessibility
- Label
- Ordered list
- Description
- Renders as an ordered list; set ariaLabel to name the sequence.
- Label
- Current step
- Description
- The active event exposes aria-current=step.
Content Adaptation
- Label
- Optional detail
- Description
- Description and timestamp render only when provided.
- Label
- Horizontal overflow
- Description
- The horizontal layout scrolls when events exceed the width.
Motion Haptics
- Motion
- Label
- Static
- Description
- Timeline does not animate state transitions.
- Haptics
- Label
- No feedback
- Description
- Timeline is non-interactive and requests no haptics.