Timeline

new

One thing after another. A record of events with an optional current one, vertical or horizontal, newest first or last.

Demo
  1. Project kickoff
    Aligned the team, set the milestones and allocated resources.
  2. Design phase
    User research, wireframes and prototypes for testing.
  3. Development sprint
    Core features, API integration and the first internal build.
  4. Testing and release
    QA, performance work and the production deploy.

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: an ol; holds the current value through v-model or default-value
  • TimelineItem: an li with a value; carries data-state and aria-current="step" when current
  • TimelineIndicator: the circle, with an icon, a number, an Avatar or nothing
  • TimelineSeparator: the line to the next record; hidden on the last one
  • TimelineContent: the text column; TimelineDate (a time), TimelineTitle and TimelineDescription go 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.

Horizontal
  1. Kickoff
    Team alignment.
  2. Design
    Wireframes and prototypes.
  3. Build
    Features and APIs.
  4. Release
    QA and deploy.

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.

Reverse
  1. 2.0
    Version 2.0
    New theme and radius roles.
  2. 1.5
    Version 1.5
    Swipe views and drawers.
  3. 1.0
    Version 1.0
    First stable release.
  4. 0.1
    Version 0.1
    Buttons, inputs and a theme.

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.

Alternating
  1. Kickoff
    Team alignment.
  2. Design
    Wireframes and prototypes.
  3. Build
    Features and APIs.
  4. Release
    QA and deploy.

Changelog

No model, rich content: a Badge in the title, the date beside it, paragraphs in the description with as="div".

Changelog
  1. registry 0.15.0

    Timeline: eight parts for a record of events, with a current one, in five sizes and six colours.

    Marquee: content that scrolls forever, with a pause on hover and a fade at the edges.

  2. Regression in Select
    The list opened under a sticky header. Fixed in 0.14.1 the same day.
  3. core 0.14.0
    Radius roles and the swipe-snap pager.

API Reference

Every part takes a class that merges with its own.

Data attributes

data-slotAttributesDescription
timelinedata-orientation, data-reverse, data-color, data-sizeThe root, an ol.
timeline-itemdata-state, data-orientation, aria-currentOne record; data-state is active, completed or inactive, absent without a model, and aria-current="step" marks the current one.
timeline-indicatordata-colorThe circle; data-color only when the part has its own colour.
timeline-separatordata-orientationThe line after a record, decorative, hidden on the last one.
timeline-contentdata-orientationThe 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.

VariableDefaultDescription
--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-textvar(--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.

Changelog

  1. registry 0.21.0

    e5495ef — size works the same way everywhere. Every component exports its size type (AlertSize, BadgeSize, CardSize, CheckboxSize, RadioSize, SwitchSize, EmptySize, InputFloatingSize, ItemSize, ListboxSize, SeparatorSize, SliderSize, StepperSize, TabsSize, TextareaSize, TimelineSize) and the props take it without null; Button-based parts take ButtonSize, Input TextControlSize, SelectTrigger SelectSize and Tree TreeSize. ToggleGroup and ToolbarToggleGroup carry data-size on the group as well. Table's row heights moved into tableSize, so a class on DataTable's ui.table overrides --table-row-h at every size, not only at md.

  2. registry 0.20.0

    b7a84d5 — New Timeline: a record of events with an optional current one. Eight parts (Timeline, TimelineItem, TimelineIndicator, TimelineSeparator, TimelineContent, TimelineDate, TimelineTitle, TimelineDescription), v-model/default-value for the current record, reverse for lists that run newest first, orientation, size from xs to xl as the record's density through --timeline-* variables on the root, and color on the root or on one indicator.