Timeline
A timeline places markers in a sequence, joins them with a connector, and puts content beside each one.
- HanoiTwo nights in the Old Quarter
- Ninh BinhOne night, boats through Tam Coc in the morning
- Hoi AnThree nights on An Bang beach
Installation
npx shadcn@latest add @flyingsalmon/timelineUsage
import {
Timeline,
TimelineContent,
TimelineDescription,
TimelineItem,
TimelineMarker,
TimelineTitle,
} from '@/components/ui/timeline'
export function TripRoute() {
return (
<Timeline>
<TimelineItem>
<TimelineMarker />
<TimelineContent>
<TimelineTitle>Hanoi</TimelineTitle>
<TimelineDescription>Two nights</TimelineDescription>
</TimelineContent>
</TimelineItem>
<TimelineItem>
<TimelineMarker />
<TimelineContent>
<TimelineTitle>Hoi An</TimelineTitle>
<TimelineDescription>Three nights</TimelineDescription>
</TimelineContent>
</TimelineItem>
</Timeline>
)
}Examples
Marker sizes
A marker is a slot. Empty, it draws a neutral dot; with an icon, a bordered circle. Small markers suit the legs between places, and both sizes centre on the same line, so the connector stays straight.
- HanoiTwo nights in the Old Quarter
- Train to Ninh Binh2h 20m from Hanoi station
- Ninh BinhOne night
- Flight to Da Nang1h 20m, lands at midday
- Hoi AnThree nights on An Bang beach
Linked title
Put an anchor in the title and it takes the underline, the colour, and the hover. Add the offset focus ring from the interaction lib to the anchor; the timeline itself stays free of that dependency.
- Two nights in the Old Quarter
- Ninh BinhOne night
Horizontal
Content sits below the marker and every item takes an equal share of the width, so markers stay evenly spaced however long the content runs.
- Hanoi2 nights
- Ninh Binh1 night
- Hoi An3 nights
Strip
A strip is a horizontal timeline whose items leave out TimelineContent. There is no separate component and no hidden-content mode.
Spacing
The gap between items comes from --timeline-spacing on the root, and the connectors that bridge the gaps follow it. Set it with className.
- Hanoi
- Ninh Binh
- Hoi An
A moving current marker
Press Next day. The current marker travels from day to day.
Guidelines
When to use
- To show a route or an itinerary: cities, legs between them, days of a trip.
- When each item has a title and a line of detail that belong beside its marker.
When not to use
Do and don’t
- DoLet the marker say what kind of stop it is, and give every stop of one kind the same marker: an icon for a leg, a dot for a place.The traveller reads the rhythm of the route from its markers before reading a word.
- DoMark the current stop with a marker of your own, and let it travel to the next stop when the traveller moves on.The rail gives every stop the same neutral mark, because done, current, and ahead are claims only your app can make. A marker that travels shows the move instead of redrawing the rail.
- Don’tPut an action on each stop. The action the route leads to, such as approving it, sits below the whole timeline.A route is read top to bottom and then acted on once. Buttons on every stop turn it into a list of chores.
- Don’tStretch a link over a whole item.An item is never a hit target; only its title links. One linked title costs the keyboard user one stop, however many cities the rail holds.
Accessibility
| Key | Description |
|---|---|
| Tab | Reaches one stop per linked title, in document order. Nothing else in the timeline is focusable. |
| Enter | Follows the focused link in a title. |
The root is an ol and every item an li, so a screen reader announces the order and the count with no extra ARIA. The connector is hidden from assistive technology. Icons you put in a marker should be decorative too, because the title beside the marker already names the stop.
API
Timeline
Also takes every <ol> attribute. Every part carries a data-slot, and the root exposes data-orientation for styling around it.
| Prop | Type | Default | Description |
|---|---|---|---|
| orientation | TimelineOrientation | TimelineOrientation.Vertical | Vertical puts content beside the marker. Horizontal puts it below and shares the width equally. |
TimelineMarker
Also takes every <span> attribute. It draws the connector to the next item; the last item and an item with no marker have none. It has no status or active state: paint a current marker through its children.
| Prop | Type | Default | Description |
|---|---|---|---|
| size | TimelineMarkerSize | TimelineMarkerSize.Default | Default or Small. Both centre on the same line, so a vertical rail can mix them. A horizontal timeline uses one size throughout: each connector spans from its own marker’s edge, so mixed sizes overshoot at one end. |
| children | ReactNode | – | An icon or a custom mark. Empty, the marker draws a neutral dot. |
TimelineItem takes the <li> props. TimelineContent, TimelineTitle, and TimelineDescription take the <div> props; title and description mirror the card’s typography.