Timeline

STimeline shows a sequence of events on a rail: delivery stages, an audit log, a release history. The component is data-driven — the events come from items, there is no separate item component.

The feed is exposed as role="list" with role="listitem" items rather than ul/li: library markup stays neutral so host styles cannot reach it through tag selectors.

Basic usage

Without v-model nothing is marked as completed — the timeline is a plain feed of events.

March 3

Order created

Paid by card

March 4

Packed

Warehouse 12

March 5

Shipped

Courier assigned

<script setup lang="ts">
const items = [
  {
    title: 'Order created',
    description: 'Paid by card',
    date: 'March 3',
  },
  {
    title: 'Packed',
    description: 'Warehouse 12',
    date: 'March 4',
  },
  {
    title: 'Shipped',
    description: 'Courier assigned',
    date: 'March 5',
  },
]
</script>

<template>
  <STimeline :items="items" />
</template>

Progress

v-model holds the value of the current item (or its index when the items have no value). Everything before it is drawn as completed — a filled indicator with a check mark and a filled rail segment; the current item is highlighted, the rest stay muted.

March 3

Order created

March 4

Packed

March 5

Shipped

March 7

Delivered

<script setup lang="ts">
import { ref } from 'vue'

const current = ref('packed')
const items = [
  {
    value: 'created',
    title: 'Order created',
    date: 'March 3',
  },
  {
    value: 'packed',
    title: 'Packed',
    date: 'March 4',
  },
  {
    value: 'shipped',
    title: 'Shipped',
    date: 'March 5',
  },
  {
    value: 'delivered',
    title: 'Delivered',
    date: 'March 7',
  },
]
</script>

<template>
  <STimeline
    v-model="current"
    :items="items"
  />
</template>

Icons and colors

item.icon replaces the dot with an icon from the registry, item.color accents a single event with a name from the palette, and disabled dims an event that did not happen. The timeline-wide color sets the accent of the completed part, and text-color the content on it — the check or the icon inside a completed indicator. An item that brings a light accent of its own overrides that content color with item.textColor; without it the item falls back to the timeline's.

March 1

Draft

March 2

In review

March 3

Rejected

Archived

<template>
  <STimeline
    v-model="current"
    color="teal"
    :items="[
      { value: 'draft', title: 'Draft', icon: 'pencil', date: 'March 1' },
      { value: 'review', title: 'In review', icon: 'eye', date: 'March 2' },
      {
        value: 'rejected',
        title: 'Rejected',
        icon: 'circle-x',
        color: 'negative',
        date: 'March 3',
      },
      { value: 'archived', title: 'Archived', icon: 'folder', disabled: true },
    ]"
  />
</template>

Horizontal orientation

orientation="horizontal" lays the events out in a row with the rail running across; size scales the indicator, the spacing and the type scale.

Mon

Ordered

Tue

Packed

Wed

Shipped

Fri

Delivered

<script setup lang="ts">
import { ref } from 'vue'

const current = ref(2)
const items = [
  { title: 'Ordered', date: 'Mon' },
  { title: 'Packed', date: 'Tue' },
  { title: 'Shipped', date: 'Wed' },
  { title: 'Delivered', date: 'Fri' },
]
</script>

<template>
  <STimeline
    v-model="current"
    orientation="horizontal"
    size="sm"
    :items="items"
  />
</template>

Label placement

label-placement picks the side of the dot the event text goes to. start and end put it beside the dot, top and bottom above or below it — and there the event becomes a centred column, so the text lines up with the middle of the dot instead of starting at its edge. Without the prop the text is beside the dot in a vertical timeline and below it in a horizontal one: a shared default would move the text as soon as the orientation changed.

In a vertical timeline the text takes the column beside the dots, so the block is as wide as you let it be: cap it with max-width to keep the rail close to the text instead of stretched across the page.

March 3

Order created

March 4

Packed

March 5

Shipped

<script setup lang="ts">
import { ref } from 'vue'

const current = ref('packed')
const items = [
  { value: 'created', title: 'Order created', date: 'March 3' },
  { value: 'packed', title: 'Packed', date: 'March 4' },
  { value: 'shipped', title: 'Shipped', date: 'March 5' },
]
</script>

<template>
  <STimeline
    v-model="current"
    label-placement="start"
    style="max-width: 280px"
    :items="items"
  />
</template>

A horizontal timeline spans its container instead: the rail needs the width to space the events evenly, and top or bottom centres each caption on its own dot.

Mon

Ordered

Tue

Packed

Wed

Shipped

Fri

Delivered

<script setup lang="ts">
import { ref } from 'vue'

const current = ref(2)
const items = [
  { title: 'Ordered', date: 'Mon' },
  { title: 'Packed', date: 'Tue' },
  { title: 'Shipped', date: 'Wed' },
  { title: 'Delivered', date: 'Fri' },
]
</script>

<template>
  <STimeline
    v-model="current"
    orientation="horizontal"
    size="sm"
    label-placement="top"
    :items="items"
  />
</template>

Collapsing on a narrow container

stack-at is the width in pixels below which a horizontal timeline turns into a vertical one. It is compared with the width available to the timeline, not the window: inside a narrow column or a modal the rail runs out of room long before the screen does. narrow-orientation sets what the layout collapses to — vertical by default, or horizontal to get the reverse. Resize the window to see the demo switch.

Mon

Ordered

Tue

Packed

Wed

Shipped

Fri

Delivered

<script setup lang="ts">
import { ref } from 'vue'

const current = ref(2)
const items = [
  { title: 'Ordered', date: 'Mon' },
  { title: 'Packed', date: 'Tue' },
  { title: 'Shipped', date: 'Wed' },
  { title: 'Delivered', date: 'Fri' },
]
</script>

<template>
  <STimeline
    v-model="current"
    orientation="horizontal"
    size="sm"
    :stack-at="560"
    :items="items"
  />
</template>

Slots

indicator, date, title and description are scoped slots: each one receives { item, index, active, completed }, so the markup can depend on the state of the event.

✓

10:02

Commit

2

10:04

Build

Running right now

3

Deploy

<script setup lang="ts">
import { ref } from 'vue'

const current = ref('build')
const items = [
  { value: 'commit', title: 'Commit', date: '10:02' },
  { value: 'build', title: 'Build', date: '10:04' },
  { value: 'deploy', title: 'Deploy' },
]
</script>

<template>
  <STimeline
    v-model="current"
    :items="items"
  >
    <template #indicator="{ index, completed }">
      <span class="step-number">
        {{ completed ? '✓' : index + 1 }}
      </span>
    </template>
    <template #description="{ active }">
      <span v-if="active"> Running right now </span>
    </template>
  </STimeline>
</template>

API

Props

Name	Type	Default	Description
items*	{ value?: string | number; title?: string; description?: string; date?: string; icon?: string; color?: string; textColor?: SColorName; disabled?: boolean }[]	required	Events in display order.
orientation	"horizontal" | "vertical"	"vertical"	Layout direction: a column of events or a row with a horizontal rail.
label-placement	| "start" | "top" | "bottom" | "end"	undefined	Side of the indicator where the event text goes: top and bottom are above and below the dot, start and end are before and after it (left and right in a left-to-right layout). Alongside the dot the text is centred on it; above or below it the event becomes a centred column. Works in both orientations. Without a value the text is beside the dot in the vertical layout and below it in the horizontal one — there is no shared default, otherwise changing the orientation would move the text.
stack-at	number	undefined	Width in pixels below which a horizontal timeline switches to vertical. It is compared with the width available to the timeline, not the window: in a narrow column or a modal the rail breaks even on a wide screen. Without the prop the layout never changes.
narrow-orientation	"horizontal" | "vertical"	"vertical"	Orientation below the stack-at threshold. vertical by default; horizontal together with orientation="vertical" gives the reverse: a column when wide and a row when narrow.
size	"md" | "sm" | "lg"	"md"	Size: scales the indicator, the spacing and the type scale.
color	string	undefined	Accent color of the completed part: a name from the palette (primary/teal/teal-10).
text-color	string	undefined	Color of the content on the completed indicator fill: a name from the palette. White by default.
model-value	string | number	undefined	Current item: the value of item.value, or the index for items without one. Without a value nothing is completed and the timeline is a plain feed.

Events

Name	Signature	Description
update:modelValue	(value: string | number | undefined) => void	Emitted when modelValue changes. Used for two-way binding (v-model).

Slots

Name	Description
indicator	Indicator content: replaces the dot, the item icon and the completed check mark.
title	Item title (alternative to item.title).
description	Item description (alternative to item.description).
date	Item date (alternative to item.date).