A composable React timeline for web activity feeds, event histories, and milestones.
Timeline is for read-only chronology: activity feeds, audit trails, incident history, release logs, and milestone roadmaps. Use Stepper when the user is moving through a known sequence where current, complete, and upcoming steps are the primary meaning.
Import the Timeline component and access all parts using dot notation.
import {Timeline} from "@heroui-pro/react";
<Timeline>
<Timeline.Item>
<Timeline.Rail>
<Timeline.Marker />
<Timeline.Connector />
</Timeline.Rail>
<Timeline.Content>
<article>
<h3>Event title</h3>
<time dateTime="2026-05-22">May 22, 2026</time>
<p>Event details</p>
</article>
</Timeline.Content>
</Timeline.Item>
</Timeline>;Timeline intentionally owns only the chronology layout. It renders an ol with li items,
keeps connectors decorative, hides empty markers from assistive technology, and marks
status="current" items with aria-current="true". Use semantic HTML and OSS components such as
Card, Chip, and Avatar inside Timeline.Content for the event content itself.
The root component. Renders an ordered list and provides axis, placement, size, density, and item alignment context.
| Prop | Type | Default | Description |
|---|---|---|---|
axis | 'start' | 'center' | 'start' | Position of the timeline rail |
placement | 'start' | 'end' | 'alternate' | 'end' | Default side for item content; alternate alternates by item index |
size | 'sm' | 'md' | 'lg' | 'md' | Marker and text size |
density | 'compact' | 'comfortable' | 'comfortable' | Vertical rhythm between events |
itemAlign | 'start' | 'center' | 'start' | Default vertical alignment for item content |
children | ReactNode | - | Timeline items |
Also supports all native ol HTML attributes.
A single event in the timeline.
| Prop | Type | Default | Description |
|---|---|---|---|
status | 'default' | 'current' | 'success' | 'warning' | 'danger' | 'muted' | 'default' | Marker tone |
align | 'start' | 'center' | inherited | Vertical alignment for item content |
side | 'start' | 'end' | inherited | Content side for centered timelines |
children | ReactNode | - | Item parts |
Also supports all native li HTML attributes.
Rail wrapper for the marker and connector. If omitted, Timeline.Item renders a default rail.
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | - | Marker and connector content |
Also supports all native span HTML attributes.
The event marker. If omitted, Timeline.Rail renders a default marker. Empty markers are
decorative and hidden from assistive technology.
| Prop | Type | Default | Description |
|---|---|---|---|
status | 'default' | 'current' | 'success' | 'warning' | 'danger' | 'muted' | item status | Marker tone override |
children | ReactNode | - | Custom marker content |
Also supports all native span HTML attributes.
Connector line after the current item. It is hidden automatically for the last item.
| Prop | Type | Default | Description |
|---|---|---|---|
force | boolean | false | Force rendering even on the last item |
Also supports all native span HTML attributes.
Main event content. In centered timelines, side controls which side of the axis it occupies.
| Prop | Type | Default | Description |
|---|---|---|---|
side | 'start' | 'end' | item side | Content side |
children | ReactNode | - | Content parts |
Also supports all native div HTML attributes.
Hook to access per-item context from descendants of Timeline.Item.
| Property | Type | Description |
|---|---|---|
align | 'start' | 'center' | Resolved item content alignment |
index | number | Zero-based item index |
isLast | boolean | Whether this is the final timeline item |
side | 'start' | 'end' | Resolved item side |
status | 'default' | 'current' | 'success' | 'warning' | 'danger' | 'muted' | Item marker status |