---
title: Timeline
description: A list that shows events in time order.
category: Data
status: beta
since: 0.3.4
tags: [timeline, audit, status]
syncStatus: reviewed
verified: true
---

## Usage

### Basic
`color` sets each dot's semantic tone.
:::TuffDemoWrapper{demo="TimelineTimelineDemo" code-lang="vue"}
---
code: |
  <template>
    <TxTimeline>
      <TxTimelineItem title="Design phase" time="09:30" color="primary" />
      <TxTimelineItem title="Build" time="12:00" color="success" />
      <TxTimelineItem title="Launch" time="16:10" color="warning" />
    </TxTimeline>
  </template>
---
:::

### Admin Audit Flow
In a permission orchestration panel, the timeline records authorization steps and `active` marks the current one.
::TuffDemoWrapper{demo="ComponentsPermissionOrchestrationDemo" code-lang="vue"}
---
code: |
  <template>
    <TxTimeline>
      <TxTimelineItem title="Pick scope" time="09:30" color="primary">
        release
      </TxTimelineItem>
      <TxTimelineItem title="Assign resources" time="10:20" color="success" active>
        docs + notes
      </TxTimelineItem>
      <TxTimelineItem title="Await review" time="11:05" color="warning">
        security review
      </TxTimelineItem>
    </TxTimeline>
  </template>
---
::

### Best Practices

- Put the status in `title` or the slot text; use `color` only as reinforcement.
- Mark exactly one current event `active` in a step-by-step flow.
- Use `layout="horizontal"` for short milestone sequences; keep audit logs and long histories vertical.
- Keep `time` short and consistently formatted within one timeline.
- In dense timelines, give an `icon` only to exceptional or key states.

## API Reference

### TxTimeline

#### Props
:::TuffPropsTable
---
rows:
  - name: layout
    type: "'vertical' | 'horizontal'"
    default: "'vertical'"
    description: Layout direction, shared with every item.
---
:::

#### Slots

| Slot | Props | Description |
|------|------|------|
| `default` | - | Timeline items. |

### TxTimelineItem

#### Props
:::TuffPropsTable
---
rows:
  - name: title
    type: string
    default: '-'
    description: Item title.
  - name: time
    type: string
    default: '-'
    description: Time label.
  - name: color
    type: "'default' | 'primary' | 'success' | 'warning' | 'error'"
    default: "'default'"
    description: Semantic tone of the dot.
  - name: icon
    type: string
    default: '-'
    description: Dot icon.
  - name: active
    type: boolean
    default: 'false'
    description: Highlights the current event's item and dot.
---
:::

#### Slots

| Slot | Props | Description |
|------|------|------|
| `default` | - | Event description below the title and time. |

## Overview

- `TxTimeline` is a `role="list"`, and each `TxTimelineItem` a `role="listitem"`.
- `layout` reaches the items through provide / inject, so items never set it themselves.
- The dot and its icon are `aria-hidden`; screen readers get only the title, time, and description.

## Technologies

- Source: `packages/tuffex/packages/components/src/timeline/`.

<TuffDocSourceLink />