Timeline
Flexible chronological history and process timeline with statuses, alignment, details, and responsive layouts
Timeline renders a sequence of events, milestones, process steps, or activity records along a visual line. It supports vertical and horizontal layouts, left/right/alternating alignment, status markers, custom icons, dates, descriptions, arbitrary content, actions, expandable details, controlled state, and several visual variants.
See the live Timeline showcase.
Basic usage
import { Timeline } from '@mosmox/ui';
<Timeline
aria-label="Order history"
items={[
{ key: 'placed', date: '09:30', title: 'Order placed', status: 'completed' },
{ key: 'packing', date: '10:15', title: 'Packing in progress', status: 'current' },
{ key: 'delivery', title: 'Out for delivery', status: 'pending' },
]}
/>Every item needs a stable key and title. date, description, content, actions, and details are optional.
Statuses and custom markers
status accepts default, pending, current, completed, success, warning, and error. Statuses style the marker and communicate progress. Use icon when the marker should show application-specific content.
<Timeline items={[
{ key: 'done', title: 'Approved', status: 'success' },
{ key: 'review', title: 'Needs review', status: 'warning', icon: <AlertTriangle size={14} /> },
{ key: 'failed', title: 'Build failed', status: 'error' },
]} />Alignment, orientation, and variants
<Timeline items={events} align="alternate" variant="bordered" />
<Timeline items={milestones} orientation="horizontal" variant="card" lineStyle="dashed" />
<Timeline items={events} align="end" size="sm" variant="compact" />Vertical timelines support start, end, and alternate alignment. Horizontal timelines lay events out as a scrollable roadmap. default is an open timeline, compact reduces density, bordered wraps the list, and card gives each event a surface.
Details and actions
<Timeline
collapsible
defaultExpandedKeys={['review']}
items={[
{
key: 'review',
title: 'Design review',
description: 'The team reviewed the new flow.',
details: <p>Additional notes, links, or audit information.</p>,
actions: <Button size="sm">Open review</Button>,
},
]}
/>content is always visible. details is rendered behind a disclosure control when collapsible is enabled. actions accepts any React content, including buttons and links.
Controlled active and expanded state
<Timeline
activeKey={activeKey}
items={events}
onActiveChange={(key, item) => {
setActiveKey(key);
analytics.track('timeline-select', { key: item.key });
}}
expandedKeys={expandedKeys}
onExpandedChange={(keys) => setExpandedKeys(keys)}
/>Use defaultActiveKey and defaultExpandedKeys for local state. reverse changes visual order without mutating the input array. maxHeight creates a scrollable timeline for long histories.
API reference
TimelineItem
| Property | Type | Description |
|---|---|---|
key | string | Required stable identity. |
title | ReactNode | Required event title. |
date | ReactNode | Optional date or time label. |
description | ReactNode | Supporting text. |
content | ReactNode | Always-visible custom content. |
details | ReactNode | Expandable content when collapsible is enabled. |
actions | ReactNode | Buttons, links, or other actions. |
icon | ReactNode | Custom marker icon. |
status | TimelineStatus | Marker state and semantic visual tone. |
href | string | Makes the title a link. |
disabled | boolean | Disables marker selection and dims the event. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
items | TimelineItem[] | required | Events in the timeline. |
orientation | vertical | horizontal | vertical | Timeline direction. |
align | start | end | alternate | start | Content placement in vertical mode. |
size | sm | default | lg | default | Density and type scale. |
variant | default | compact | bordered | card | default | Visual presentation. |
lineStyle | solid | dashed | dotted | solid | Connector line style. |
reverse | boolean | false | Renders items in reverse order. |
activeKey / defaultActiveKey | string | — | Controlled or initial active event. |
onActiveChange | (key, item) => void | — | Called when an enabled marker is selected. |
collapsible | boolean | false | Enables expandable item details. |
expandedKeys / defaultExpandedKeys | string[] | [] | Controlled or initial expanded items. |
onExpandedChange | (keys, item) => void | — | Called after details are toggled. |
maxHeight | number | string | — | Maximum height before scrolling. |
className / style | string / CSSProperties | — | Custom root styling. |
When to use Timeline
Use Timeline for chronological histories, audit trails, project milestones, delivery status, activity records, and roadmaps. Use ChangeLog for release notes with version/category grouping, and use Stepper when the user is actively moving through a fixed sequence of form or workflow steps.
Accessibility
Provide a meaningful aria-label. The root uses a labelled section, event titles remain semantic headings, markers are keyboard-operable buttons, active state is exposed with aria-current, and expandable details expose aria-expanded.