Timeline
Ordered sequence of events with status markers and a connector line
Category: display · WCAG 2.2-AA · timeline, steps, history, progress, events
Variants
- vertical
- horizontal
States
- complete
- current
- upcoming
Props
| Prop | Type | Default | Description |
|---|---|---|---|
items | { id: string; title: ReactNode; description?: ReactNode; time?: string; icon?: ReactNode; status?: "complete" | "current" | "upcoming"; tone?: "neutral" | "info" | "success" | "warning" | "danger" }[] | — | The items to render. |
orientation | 'vertical' | 'horizontal' | vertical | Axis the entries flow along: `vertical` stacks them down the page (the usual reading order), `horizontal` runs them across. |
Design tokens
--cascivo-color-border--cascivo-color-border-strong--cascivo-color-surface--cascivo-color-success--cascivo-color-primary--cascivo-color-info--cascivo-color-warning--cascivo-color-destructive--cascivo-radius-full
When to use
- Showing an ordered sequence of events over time (activity feeds, order tracking)
- Communicating progress through discrete stages with complete/current/upcoming status
- Presenting a chronological history where order is meaningful
When not to use
- Interactive multi-step navigation the user controls — use Tabs or a Stepper
- Unordered lists where sequence carries no meaning — use List
How to build an accessible Timeline in React →
Examples
Vertical timeline with statuses
<Timeline
items={[
{ id: '1', title: 'Order placed', time: '09:00', status: 'complete' },
{ id: '2', title: 'Shipped', time: '12:30', status: 'current' },
{ id: '3', title: 'Delivered', status: 'upcoming' },
]}
/>Activity feed coloured by entry type
In a feed every entry is equally done, so `tone` — not `status` — is what separates them. Keep the meaning in the text too; colour alone is not perceivable.
<Timeline
items={[
{ id: '1', title: 'p99 latency 4.2s', description: 'ALERT · monitor', time: '14:28', tone: 'danger' },
{ id: '2', title: 'Rolling back deploy 4821', description: 'NOTE · bo', time: '14:49', tone: 'neutral' },
{ id: '3', title: 'Status changed to monitoring', description: 'STATUS · ana', time: '15:12', tone: 'info' },
{ id: '4', title: 'Merged 2 edits from kim', description: 'MERGE · sync', time: '15:14', tone: 'success' },
]}
/>Related components
- List — List is for unordered prose; Timeline conveys ordered, time-stamped events