Timeline

Component Status

Design Usage

Timeline vertically organizes a series of events, steps, or milestones in chronological order. It supports multiple marker types and flexible content layouts.

It is composed of a main container (Timeline) with steps (TimelineStep) that include a marker (TimelineMarker), optional heading (TimelineHeading), and optional content (TimelineContent).

Timeline uses a grid-based layout to align markers and content consistently. Connector lines are rendered with pseudo-elements for clean, semantic markup.

Headings are optional but recommended for clarity, especially when describing distinct phases or milestones.

---

When to Use

• To represent chronological events (e.g. history, roadmap, project milestones).
• When you need to communicate the order between items.
• To show status updates or workflows with clear visual separation of steps.

---

When Not to Use

• To display horizontally organised items.
• To display progress (e.g., onboarding, registration flow, etc.) where items should be interactive.
• If events or items do not have a logical sequence or time order.
• When a simpler list or table communicates the information more clearly.
• If the number of steps is very large, which may lead to visual clutter. Consider grouping or summarizing instead.
• When the relationship between items is not sequential but hierarchical or categorical. Consider using Card or Grid.

---

Best Practices

• Use the semantic defaults: ol for ordered timelines, ul for unordered.
• Keep marker content short and meaningful – e.g. single numbers, dots, or concise icons.
• Use headings for clarity when steps need distinct labels, and pair them with concise descriptions in TimelineContent.
• Ensure sufficient contrast for markers, headings, and connectors for accessibility.
• Keep the number of steps reasonable; break down very long timelines into sections or use progressive disclosure.
• Test across screen sizes: Timeline should remain readable and scannable on both desktop and mobile.