Timeline
newOne thing after another. A record of events with an optional current one, vertical or horizontal, newest first or last.
Open Props in the corner of the example to try color and size. color fills the reached indicators and lines, in Button's colours or your own; color on one TimelineIndicator retones that record alone: a failed deploy in a green log.
size is the density of a record, from xs (24px indicator) to xl (48px): the indicator, its icon, the gaps, the line and the space between records follow it. The title and description keep their text size.
Installation
Usage
<script setup lang="ts">
import {
Timeline,
TimelineContent,
TimelineDate,
TimelineDescription,
TimelineIndicator,
TimelineItem,
TimelineSeparator,
TimelineTitle,
} from '@/components/ui/timeline'
</script>
<template>
<Timeline default-value="design">
<TimelineItem value="kickoff">
<TimelineIndicator><Rocket /></TimelineIndicator>
<TimelineSeparator />
<TimelineContent>
<TimelineDate datetime="2026-03-15">Mar 15, 2026</TimelineDate>
<TimelineTitle>Project kickoff</TimelineTitle>
<TimelineDescription>Aligned the team and set the milestones.</TimelineDescription>
</TimelineContent>
</TimelineItem>
<TimelineItem value="design">…</TimelineItem>
</Timeline>
</template>
A timeline is a record, not a control. Unlike a Stepper it has no triggers, no keyboard navigation and no linear rule: the model only says which record is current, and the parts draw a trail up to it.
Timeline: anol; holds the currentvaluethroughv-modelordefault-valueTimelineItem: anliwith avalue; carriesdata-stateandaria-current="step"when currentTimelineIndicator: the circle, with an icon, a number, an Avatar or nothingTimelineSeparator: the line to the next record; hidden on the last oneTimelineContent: the text column;TimelineDate(atime),TimelineTitleandTimelineDescriptiongo inside
Each TimelineItem must be a direct child of Timeline: the root keeps them in document order and hides the last line.
With a model, the current record is active, the ones before it completed and the rest inactive; the state lands as data-state on the item, and the indicator and the line colour themselves from it. Without a model there is no state: every indicator is in colour and every line is muted, the look of a log where everything has happened. A record without a value matches the model by its index, and a model that matches no record counts as past the last one, so every record is completed. The state is computed from the order of the records as they mount, so it is in the server-rendered HTML and nothing flips on hydration.
Examples
Horizontal
orientation="horizontal" lays the records out in a row with the content under each indicator. Give the timeline a minimum width and let its container scroll.
Newest first
With reverse the records after the current one count as completed, for a list that runs from the latest release down. The line after the current record is coloured too, since it leads to completed ones.
Alternating
Each item is a grid, so classes on the parts move the columns around: three columns, the indicator and the line in the middle, the content on alternating sides.
Changelog
No model, rich content: a Badge in the title, the date beside it, paragraphs in the description with as="div".
API Reference
Every part takes a class that merges with its own.
Timeline
class is also accepted on every part and merged over its classes with tailwind-merge.
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | "ol" | AsTag | ComponentThe element or component to render. An |
| modelValue | undefined | TimelineValue | nullThe |
| defaultValue | undefined | TimelineValue | nullThe current record at first when |
| reverse | false | booleanCounts the records after the current one as completed instead of the ones before, for a list that runs newest first. |
| orientation | "vertical" | TimelineOrientation
|
| size | "md" | TimelineSizeThe density of a record, from |
| color | "primary" | TimelineColor | (string & {})Colour role of the reached indicators and lines, |
| Event | Payload and description |
|---|---|
| update:modelValue | [value: TimelineValue]Declared so |
| Slot | Scope and description |
|---|---|
| default | {}The |
TimelineItem
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | "li" | AsTag | ComponentThe element or component to render. An |
| value | undefined | TimelineValueWhat the model matches, a string or a number. Without it the record's index in document order, so a numeric model without values picks by index. |
| Slot | Scope and description |
|---|---|
| default | { state: TimelineState | undefined; }The indicator, the separator and the content. Receives |
TimelineIndicator
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | "div" | AsTag | ComponentThe element or component to render. A |
| color | — | TimelineColor | (string & {})Colour role of this record only, over the timeline's. Any name declared on |
| Slot | Scope and description |
|---|---|
| default | {}An icon, a number, an Avatar, or nothing for a plain dot. |
TimelineSeparator
| Prop | Default | Type and description |
|---|---|---|
| orientation | — | DataOrientationIgnored: the line follows the timeline's orientation. |
| decorative | — | booleanIgnored: the line is always decorative and hidden from assistive technology. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
TimelineContent
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | "div" | AsTag | ComponentThe element or component to render. A |
| Slot | Scope and description |
|---|---|
| default | {}The date, the title and the description, or anything else the record holds. |
TimelineDate
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | "time" | AsTag | ComponentThe element or component to render. A |
| Slot | Scope and description |
|---|---|
| default | {}The date as text. |
TimelineTitle
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | "div" | AsTag | ComponentA |
| Slot | Scope and description |
|---|---|
| default | {}The title. |
TimelineDescription
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | "div" | AsTag | ComponentA |
| Slot | Scope and description |
|---|---|
| default | {}The description, or a block of paragraphs with |
class is also accepted on every part and merged over its classes with tailwind-merge.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
"ol" AsTag | ComponentThe element or component to render. An<ol>by default.- modelValue
undefined TimelineValue | nullThevalueof the current record, bound withv-model;nullcounts as no model. The records before it are completed, the ones after it inactive. A value that matches no record counts as past the last one, so every record is completed (inactive withreverse). Without a model no record has a state.- defaultValue
undefined TimelineValue | nullThe current record at first whenv-modelis not used;nullcounts as no model.- reverse
false booleanCounts the records after the current one as completed instead of the ones before, for a list that runs newest first.- orientation
"vertical" TimelineOrientationverticalstacks the records,horizontallays them out in a row.verticalby default.- size
"md" TimelineSizeThe density of a record, fromxs(24px indicator) toxl(48px): indicator, icon, gaps, line thickness and the space between records. Titles and descriptions keep their text size.- color
"primary" TimelineColor | (string & {})Colour role of the reached indicators and lines,primaryby default. Any name declared on[data-slot][data-color]works too.
Emits
- update:modelValue
[value: TimelineValue]Declared sov-modelbinds; the parts never change the model themselves.
Slots
- default
{}TheTimelineItems.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
"li" AsTag | ComponentThe element or component to render. An<li>by default.- value
undefined TimelineValueWhat the model matches, a string or a number. Without it the record's index in document order, so a numeric model without values picks by index.
Slots
- default
{ state: TimelineState | undefined; }The indicator, the separator and the content. Receivesstate:active,completed,inactiveorundefinedwithout a model.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
"div" AsTag | ComponentThe element or component to render. A<div>by default.- color
TimelineColor | (string & {})Colour role of this record only, over the timeline's. Any name declared on[data-slot][data-color]works too.
Slots
- default
{}An icon, a number, an Avatar, or nothing for a plain dot.
Props
- orientation
DataOrientationIgnored: the line follows the timeline's orientation.- decorative
booleanIgnored: the line is always decorative and hidden from assistive technology.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
"div" AsTag | ComponentThe element or component to render. A<div>by default.
Slots
- default
{}The date, the title and the description, or anything else the record holds.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
"time" AsTag | ComponentThe element or component to render. A<time>by default, so adatetimeattribute lands on it.
Slots
- default
{}The date as text.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
"div" AsTag | ComponentA<div>by default; set a heading level that fits the page.
Slots
- default
{}The title.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
"div" AsTag | ComponentA<div>by default.
Slots
- default
{}The description, or a block of paragraphs withas="div".
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| timeline | data-orientation, data-reverse, data-color, data-size | The root, an ol. |
| timeline-item | data-state, data-orientation, aria-current | One record; data-state is active, completed or inactive, absent without a model, and aria-current="step" marks the current one. |
| timeline-indicator | data-color | The circle; data-color only when the part has its own colour. |
| timeline-separator | data-orientation | The line after a record, decorative, hidden on the last one. |
| timeline-content | data-orientation | The text column. |
| timeline-date | — | A time. |
| timeline-title | — | The title. |
| timeline-description | — | The description. |
CSS variables
Set on the root by size; a class on a part wins over them.
| Variable | Default | Description |
|---|---|---|
| --timeline-indicator | --spacing(8) | The indicator's box, 24px at xs to 48px at xl. |
| --timeline-icon | --spacing(4) | An icon in the indicator, 14px to 24px. |
| --timeline-text | var(--typescale-label-lg-size) | A number in the indicator. |
| --timeline-gap | --spacing(2) | The space between the indicator and the content, and between the indicator and the line. |
| --timeline-separator | --spacing(0.5) | The line's thickness, 1px to 4px. |
| --timeline-spacing | --spacing(6) | The space between records, 16px to 32px. |