Show dated events in order, like an activity feed, a changelog or an order's progress, with arrow keys between them.

Use a Timeline for a list of things that happened, or will: a project's activity, an order's status history, a release's milestones. It's a list for screen readers, with one tab stop for keyboards, and the arrow keys move between events.

<script setup lang="ts">
import {
  Timeline,
  TimelineConnector,
  TimelineDescription,
  TimelineItem,
  TimelineMarker,
  TimelineTime,
  TimelineTitle,
} from "@ui-sdk/vue/timeline"

const events = [
  {
    title: "Deployed to production",
    dateTime: "2026-11-10T14:32",
    time: "Today, 2:32 PM",
    description: "Version 2.4.1 is live in every region.",
  },
  {
    title: "Checks passed",
    dateTime: "2026-11-10T14:20",
    time: "Today, 2:20 PM",
    description: "312 tests and the bundle size budget.",
  },
  {
    title: "Pull request merged",
    dateTime: "2026-11-10T13:58",
    time: "Today, 1:58 PM",
    description: "Ada merged Cache search results into main.",
  },
  {
    title: "Review requested",
    dateTime: "2026-11-09T17:05",
    time: "Yesterday, 5:05 PM",
    description: "Grace and Linus were asked to review.",
  },
]
</script>

<template>
  <Timeline aria-label="Activity">
    <TimelineItem v-for="event in events" :key="event.title">
      <TimelineMarker />
      <TimelineConnector />
      <TimelineTitle>{{ event.title }}</TimelineTitle>
      <TimelineTime :datetime="event.dateTime">{{ event.time }}</TimelineTime>
      <TimelineDescription>{{ event.description }}</TimelineDescription>
    </TimelineItem>
  </Timeline>
</template>
Tab into the activity, then use Up and Down to move between events. Home and End jump to the first and last.

Installation

npm install @ui-sdk/vue @ui-sdk/core

Composition

Use the following composition to build a Timeline:

Timeline
├── TimelineItem
│   ├── TimelineMarker
│   ├── TimelineConnector
│   ├── TimelineTitle
│   ├── TimelineTime
│   └── TimelineDescription
└── TimelineItem

Every part inside an item is optional. TimelineMarker is the dot or icon on the line, and TimelineConnector the line to the next event. Both are hidden from screen readers, so they're only for looks.

Usage

Import the parts and put them together:

<script setup lang="ts">
import {
  Timeline,
  TimelineConnector,
  TimelineDescription,
  TimelineItem,
  TimelineMarker,
  TimelineTime,
  TimelineTitle,
} from "@ui-sdk/vue/timeline"
</script>

<template>
  <Timeline aria-label="Activity">
    <TimelineItem>
      <TimelineMarker />
      <TimelineConnector />
      <TimelineTitle>Deployed to production</TimelineTitle>
      <TimelineTime datetime="2026-11-10T14:32">2:32 PM</TimelineTime>
      <TimelineDescription>Version 2.4.1 is live.</TimelineDescription>
    </TimelineItem>
  </Timeline>
</template>

Timeline renders a <div> with the list role and each item a <div> with the listitem role. With feed, the same markup becomes a feed of articles. Pass datetime to TimelineTime, so the date is machine readable while the text stays friendly.

When focus lands on an event, screen readers read its title as its name, then its time and description. Links and buttons inside an event stay in the tab order: Tab moves from the event to them, and arrow keys pressed on them stay with them.

Horizontal

Set orientation="horizontal" for a row, like a roadmap. Left and Right move between events instead of Up and Down, and they swap in right-to-left text. Set :loop="false" to stop at either end.

<script setup lang="ts">
import {
  Timeline,
  TimelineConnector,
  TimelineItem,
  TimelineMarker,
  TimelineTime,
  TimelineTitle,
} from "@ui-sdk/vue/timeline"

const milestones = [
  { title: "Kickoff", dateTime: "2026-01", time: "January" },
  { title: "Design review", dateTime: "2026-03", time: "March" },
  { title: "Beta", dateTime: "2026-06", time: "June" },
  { title: "Launch", dateTime: "2026-09", time: "September" },
]
</script>

<template>
  <Timeline orientation="horizontal" :loop="false" aria-label="Roadmap">
    <TimelineItem v-for="milestone in milestones" :key="milestone.title">
      <TimelineMarker />
      <TimelineConnector />
      <TimelineTitle>{{ milestone.title }}</TimelineTitle>
      <TimelineTime :datetime="milestone.dateTime">
        {{ milestone.time }}
      </TimelineTime>
    </TimelineItem>
  </Timeline>
</template>
Tab into the roadmap and press Right to reach Launch. Right again stays there.

Status

Give each item a status of "complete", "current" or "upcoming" for a process, like an order's progress. The current event gets aria-current="step", and Tab lands on it first. Every part of an event shows its status with data-complete, data-current or data-upcoming.

Create a controller with createTimelineController and call its focus() with an item's value to move focus to it from anywhere.

<script setup lang="ts">
import { CheckIcon } from "@lucide/vue"
import {
  Timeline,
  TimelineConnector,
  TimelineDescription,
  TimelineItem,
  TimelineMarker,
  TimelineTime,
  TimelineTitle,
  createTimelineController,
  type TimelineStatus,
} from "@ui-sdk/vue/timeline"

const steps: {
  value: string
  title: string
  dateTime: string
  time: string
  description: string
  status: TimelineStatus
}[] = [
  {
    value: "placed",
    title: "Order placed",
    dateTime: "2026-11-01",
    time: "Nov 1",
    description: "We received your order.",
    status: "complete",
  },
  {
    value: "packed",
    title: "Packed",
    dateTime: "2026-11-02",
    time: "Nov 2",
    description: "Your items left the shelf.",
    status: "complete",
  },
  {
    value: "shipped",
    title: "Shipped",
    dateTime: "2026-11-03",
    time: "Nov 3",
    description: "On its way with the carrier.",
    status: "current",
  },
  {
    value: "delivered",
    title: "Delivered",
    dateTime: "2026-11-05",
    time: "Nov 5",
    description: "Expected by Thursday.",
    status: "upcoming",
  },
]

const controller = createTimelineController()
</script>

<template>
  <div data-slot="stack">
    <div data-slot="controls">
      <button type="button" @click="controller.focus('shipped')">
        Go to Current Step
      </button>
    </div>
    <Timeline aria-label="Order status" :controller="controller">
      <TimelineItem
        v-for="step in steps"
        :key="step.value"
        :value="step.value"
        :status="step.status"
      >
        <TimelineMarker>
          <CheckIcon v-if="step.status === 'complete'" aria-hidden="true" />
        </TimelineMarker>
        <TimelineConnector />
        <TimelineTitle>{{ step.title }}</TimelineTitle>
        <TimelineTime :datetime="step.dateTime">{{ step.time }}</TimelineTime>
        <TimelineDescription>{{ step.description }}</TimelineDescription>
      </TimelineItem>
    </Timeline>
  </div>
</template>
Tab into the order status. Focus starts on Shipped, the current step. Move away, then choose Go to Current Step.

A marker shows status only to sighted people. When the status matters, say it in the title or description too, like "Shipped, in progress".

Details

Put a Collapsible inside an item for details that can open. Its trigger is a button inside the event, so Tab reaches it after the event, and arrow keys still move between events.

<script setup lang="ts">
import { ChevronDownIcon } from "@lucide/vue"
import {
  Timeline,
  TimelineConnector,
  TimelineDescription,
  TimelineItem,
  TimelineMarker,
  TimelineTime,
  TimelineTitle,
} from "@ui-sdk/vue/timeline"
import {
  Collapsible,
  CollapsiblePanel,
  CollapsibleTrigger,
} from "@ui-sdk/vue/collapsible"

const releases = [
  {
    title: "Version 2.4",
    dateTime: "2026-10-28",
    time: "October 28",
    description: "Faster search and resumable uploads.",
    changes: [
      "Search now matches file contents, not only names.",
      "Uploads resume after the connection drops.",
    ],
  },
  {
    title: "Version 2.3",
    dateTime: "2026-09-30",
    time: "September 30",
    description: "Shared links and a new sidebar.",
    changes: [
      "Shared links remember the folder they were opened from.",
      "The sidebar collapses to icons on narrow screens.",
    ],
  },
  {
    title: "Version 2.2",
    dateTime: "2026-08-26",
    time: "August 26",
    description: "Dark mode follows your system.",
    changes: ["Dark mode follows the system setting.", "Avatars are sharper."],
  },
]
</script>

<template>
  <Timeline aria-label="Changelog">
    <TimelineItem v-for="release in releases" :key="release.title">
      <TimelineMarker />
      <TimelineConnector />
      <TimelineTitle>{{ release.title }}</TimelineTitle>
      <TimelineTime :datetime="release.dateTime">
        {{ release.time }}
      </TimelineTime>
      <TimelineDescription>{{ release.description }}</TimelineDescription>
      <Collapsible>
        <CollapsibleTrigger>
          What Changed
          <ChevronDownIcon aria-hidden="true" />
        </CollapsibleTrigger>
        <CollapsiblePanel>
          <ul>
            <li v-for="change in release.changes" :key="change">
              {{ change }}
            </li>
          </ul>
        </CollapsiblePanel>
      </Collapsible>
    </TimelineItem>
  </Timeline>
</template>
Tab to What Changed under Version 2.4 and press Enter. Shift+Tab back to the event, then press Down for Version 2.3.

Feed

Set feed for a timeline that loads more as people scroll, like a social feed. It follows the WAI-ARIA feed pattern: the root becomes a feed and each item an article with its position and the count, and Page Down and Page Up move between articles from anywhere inside one.

Set busy while you load or change articles. It sets aria-busy, so screen readers wait for the new articles before reading on.

Console
<script setup lang="ts">
import {
  Timeline,
  TimelineConnector,
  TimelineDescription,
  TimelineItem,
  TimelineMarker,
  TimelineTime,
  TimelineTitle,
} from "@ui-sdk/vue/timeline"
import { computed, ref } from "vue"
import { useLog } from "./log"

const updates = [
  {
    id: 1,
    author: "Ada",
    date: "2026-11-10",
    time: "Nov 10",
    text: "Shipped the new onboarding flow.",
  },
  {
    id: 2,
    author: "Grace",
    date: "2026-11-10",
    time: "Nov 10",
    text: "Fixed the flaky upload test.",
  },
  {
    id: 3,
    author: "Linus",
    date: "2026-11-09",
    time: "Nov 9",
    text: "Moved the docs to the new theme.",
  },
  {
    id: 4,
    author: "Margaret",
    date: "2026-11-09",
    time: "Nov 9",
    text: "Wrote the launch checklist.",
  },
  {
    id: 5,
    author: "Ada",
    date: "2026-11-08",
    time: "Nov 8",
    text: "Cut search latency in half.",
  },
  {
    id: 6,
    author: "Grace",
    date: "2026-11-07",
    time: "Nov 7",
    text: "Added keyboard shortcuts to the editor.",
  },
  {
    id: 7,
    author: "Linus",
    date: "2026-11-06",
    time: "Nov 6",
    text: "Cleaned up the old billing code.",
  },
  {
    id: 8,
    author: "Margaret",
    date: "2026-11-05",
    time: "Nov 5",
    text: "Ran the accessibility review.",
  },
  {
    id: 9,
    author: "Ada",
    date: "2026-11-04",
    time: "Nov 4",
    text: "Started the mobile layout.",
  },
]

const pageSize = 3

const log = useLog()
const count = ref(pageSize)
const busy = ref(false)
const shown = computed(() => updates.slice(0, count.value))

function loadMore() {
  busy.value = true
  setTimeout(() => {
    count.value += pageSize
    busy.value = false
    log(`Loaded ${pageSize} more updates`)
  }, 600)
}
</script>

<template>
  <div data-slot="stack">
    <div data-slot="controls">
      <button
        type="button"
        :disabled="busy || count >= updates.length"
        @click="loadMore"
      >
        {{ busy ? "Loading…" : "Load More" }}
      </button>
    </div>
    <Timeline feed :busy="busy" aria-label="Team updates">
      <TimelineItem v-for="update in shown" :key="update.id">
        <TimelineMarker />
        <TimelineConnector />
        <TimelineTitle>{{ update.author }}</TimelineTitle>
        <TimelineTime :datetime="update.date">{{ update.time }}</TimelineTime>
        <TimelineDescription>{{ update.text }}</TimelineDescription>
      </TimelineItem>
    </Timeline>
  </div>
</template>
Tab into the updates and press Page Down. Choose Load More: the feed is busy until three more updates arrive. The console logs each load.

Use a list for most timelines. A feed is for long lists that grow, where a screen reader's reading mode should flow from one article to the next.

Custom Rendering

Render any part as another element with its #render slot, like a title as a heading so people can move between events by heading. Bind the part's props onto the element with v-bind:

<TimelineTitle>
  <template #render="{ props }">
    <h3 v-bind="props">Deployed to production</h3>
  </template>
</TimelineTitle>

Parts and Composition explains the rendering contract.

Styling

The parts have no styles. Lay an item out as a grid, with the marker in its own column and the connector positioned along it. data-orientation on every part says which way the events run.

Use data-first and data-last on items to hide the connector after the last event. They're written once the events are in the page; for markup rendered on the server, :last-child does the same before it hydrates.

Each part has a data-slot, such as timeline-marker, and its state attributes are listed under Data Attributes.

Timeline writes --timeline-count, how many events it holds, and each TimelineItem writes --timeline-index, its place from 0. Use them for a horizontal row's grid columns, or to stagger an animation.

Timeline

VariableWhat it holds
--timeline-countHow many events are in the page. Size a horizontal grid's columns with it.

TimelineItem

VariableWhat it holds
--timeline-indexThe event's place among the events in the page, 0 for the first. It follows them as they move.

Data Attributes

Timeline

[data-slot="timeline"]

AttributeWhat it means
data-orientationhorizontalverticalWhich way the events run.
data-busyPresent while a feed is loading or changing events, with busy.

TimelineItem

[data-slot="timeline-item"]

AttributeWhat it means
data-completePresent when the event's status is complete.
data-orientationhorizontalverticalWhich way the events run.
data-currentPresent when the event's status is current.
data-upcomingPresent when the event's status is upcoming.
data-firstPresent on the first event. Written once it's in the page.
data-lastPresent on the last event. Written once it's in the page.

TimelineMarker

[data-slot="timeline-marker"]

AttributeWhat it means
data-completePresent when the event's status is complete.
data-orientationhorizontalverticalWhich way the events run.
data-currentPresent when the event's status is current.
data-upcomingPresent when the event's status is upcoming.

TimelineConnector

[data-slot="timeline-connector"]

AttributeWhat it means
data-completePresent when the event's status is complete.
data-orientationhorizontalverticalWhich way the events run.
data-currentPresent when the event's status is current.
data-upcomingPresent when the event's status is upcoming.

TimelineTime

[data-slot="timeline-time"]

AttributeWhat it means
data-completePresent when the event's status is complete.
data-orientationhorizontalverticalWhich way the events run.
data-currentPresent when the event's status is current.
data-upcomingPresent when the event's status is upcoming.

TimelineTitle

[data-slot="timeline-title"]

AttributeWhat it means
data-completePresent when the event's status is complete.
data-orientationhorizontalverticalWhich way the events run.
data-currentPresent when the event's status is current.
data-upcomingPresent when the event's status is upcoming.

TimelineDescription

[data-slot="timeline-description"]

AttributeWhat it means
data-completePresent when the event's status is complete.
data-orientationhorizontalverticalWhich way the events run.
data-currentPresent when the event's status is current.
data-upcomingPresent when the event's status is upcoming.

API Reference

Timeline

orientation?TimelineOrientation
Which arrow keys move between events: up and down, or left and right.
loop?boolean
Whether arrow keys wrap from the last event to the first.
feed?boolean
Whether the events are a feed that loads more as people scroll, rather than a list. Each event becomes an article with its position, and Page Down and Page Up move between them from anywhere inside one.
busy?boolean
Whether a feed is loading or changing events, which sets aria-busy so screen readers wait until it's done. Only a feed reads it.
controller?{ focus: (value?: string) => void; }
Focuses an event from anywhere. Create one with createTimelineController().
debug?boolean
Logs every state change with its reason to the console, in development builds.

TimelineItem

value?string
Names the event for the controller's focus(). Generated when left out.
status?TimelineStatus
Where the event stands in a process. The "current" one sets aria-current="step" and takes the tab stop first.

TimelineMarker, TimelineConnector, TimelineTime, TimelineTitle and TimelineDescription take no props of their own.

State

What render slots and the default slot receive on Timeline:

orientationTimelineOrientation
Which way the events run.
feedboolean
Whether the events are a feed rather than a list.
busyboolean
Whether a feed is loading or changing events.

On TimelineItem and every part inside it:

statusTimelineStatus | undefined
Where the event stands in a process, or undefined when it has no status.
orientationTimelineOrientation
Which way the events run.

Controller

focus(value?)(value?: string | undefined) => void
Moves focus to an event by its value, or to the event that holds the tab stop.

Accessibility

A timeline is a list of listitems, named with aria-label. With feed, it follows the WAI-ARIA feed pattern: a feed of articles, each with aria-posinset and aria-setsize, and aria-busy while it loads. Each event is named by its title through aria-labelledby and described by its time and description through aria-describedby. The current event has aria-current="step".

Keyboard

The events have one tab stop, a roving focus. Tab enters on the current event, else the first, then returns to the event focused last. Markup rendered on the server holds the stop on the first event until it hydrates.

KeyAction
ArrowDown / ArrowUpMove focus between events in a vertical timeline
ArrowRight / ArrowLeftMove focus between events in a horizontal timeline
Home / EndFocus the first or last event
PageDown / PageUpIn a feed, focus the next or previous article, from inside
TabMove from an event to the links and buttons inside it

Arrow keys move only from an event itself, so controls inside keep them. In right-to-left text, Left and Right swap.

Tested Behavior

Every line below is an automated test.

  • A busy feed sets aria-busy.
A list of events
  • The events are a named list of list items.
  • Each event is named by its title and described by its time and description.
  • Tab lands on the current event, then on the links inside it, then leaves.
  • The current event says it's the current step.
  • Each event and its parts show its status.
  • ArrowDown and ArrowUp move between events.
  • ArrowLeft and ArrowRight do nothing in a vertical list.
  • Home and End move to the first and last events.
  • Arrow keys wrap from the last event to the first.
  • Arrow keys on a link inside an event leave focus on the link.
  • Page Down does nothing in a list.
  • Tab comes back to the event focused last.
  • Only the event with the tab stop is in the tab order.
  • The first and last events are marked.
  • An event added at the top becomes the first.
  • Events that change places move the first and last marks.
  • Each event carries its place and the list how many there are.
  • The tab stop follows the current step when it moves before focus enters.
  • The controller moves focus to an event.
  • Markers and connectors are hidden from assistive technology.
A list that doesn't loop
  • Arrow keys stop at either end.
A horizontal list
  • ArrowRight and ArrowLeft move between events.
  • ArrowDown and ArrowUp do nothing.
A feed
  • The events are a named feed of articles.
  • Each article says where it sits and how many there are.
  • An article added at the top moves every position.
  • Articles moved inside a wrapper take their new places.
  • Page Down and Page Up move between articles.
  • Page Down from a link inside an article moves to the next article.
  • Page Down on the last article stays there.
  • The feed isn't busy until it's told.

Runs in React, Vue and web components.