---
title: Timeline
description: Vertical timeline of events
visibility: guest
draft: false
---

# Timeline

A vertical activity feed for displaying chronological events — deployments, audit logs, status updates, user activity. Each item has a colored dot indicator, optional icon, timestamp, and content area.

## Basic Usage

:::preview{title="Simple timeline"}
<x-wirekit::timeline>
    <x-wirekit::timeline.item time="2 hours ago">
        <x-slot:title>Deployed v1.2.0</x-slot:title>
        Release notes linked below.
    </x-wirekit::timeline.item>
    <x-wirekit::timeline.item time="5 hours ago">
        <x-slot:title>Tests passed</x-slot:title>
        All 142 tests green.
    </x-wirekit::timeline.item>
    <x-wirekit::timeline.item time="1 day ago">
        <x-slot:title>Branch created</x-slot:title>
        feature/new-dashboard
    </x-wirekit::timeline.item>
</x-wirekit::timeline>
:::

## With Variant Colors

Use the `variant` prop on individual items to signal different event types:

:::preview{title="Colored variants"}
<x-wirekit::timeline>
    <x-wirekit::timeline.item variant="success" time="Just now">
        <x-slot:title>Deployment successful</x-slot:title>
    </x-wirekit::timeline.item>
    <x-wirekit::timeline.item variant="warning" time="10 min ago">
        <x-slot:title>Build warning: deprecated API</x-slot:title>
    </x-wirekit::timeline.item>
    <x-wirekit::timeline.item variant="danger" time="1 hour ago">
        <x-slot:title>Pipeline failed</x-slot:title>
        Exit code 1 on test step.
    </x-wirekit::timeline.item>
    <x-wirekit::timeline.item time="2 hours ago">
        <x-slot:title>Commit pushed</x-slot:title>
    </x-wirekit::timeline.item>
</x-wirekit::timeline>
:::

## With Icons

Pass a semantic icon alias to each item:

:::preview{title="Timeline with icons"}
<x-wirekit::timeline>
    <x-wirekit::timeline.item icon="check" variant="success" time="Just now">
        <x-slot:title>Deployed</x-slot:title>
    </x-wirekit::timeline.item>
    <x-wirekit::timeline.item icon="warning" variant="warning" time="5 min ago">
        <x-slot:title>Warning issued</x-slot:title>
    </x-wirekit::timeline.item>
    <x-wirekit::timeline.item icon="close" variant="danger" time="1 hour ago">
        <x-slot:title>Build failed</x-slot:title>
    </x-wirekit::timeline.item>
</x-wirekit::timeline>
:::

## Continuation Lines

Use `before` and `after` to show dashed fade-in / fade-out lines, indicating that the visible timeline is part of a larger history. The lines use a CSS `mask-image` gradient to fade gracefully.

:::preview{title="Timeline with continuation lines"}
<x-wirekit::timeline :before="true" :after="true">
    <x-wirekit::timeline.item variant="success" time="2 hours ago">
        <x-slot:title>Deployed v1.2.0</x-slot:title>
        Release notes linked below.
    </x-wirekit::timeline.item>
    <x-wirekit::timeline.item time="5 hours ago">
        <x-slot:title>Tests passed</x-slot:title>
        All 142 tests green.
    </x-wirekit::timeline.item>
    <x-wirekit::timeline.item time="1 day ago">
        <x-slot:title>Branch created</x-slot:title>
        feature/new-dashboard
    </x-wirekit::timeline.item>
</x-wirekit::timeline>
:::

- **`before`** — dashed line that fades in from the top, indicating earlier events exist above
- **`after`** — dashed line that fades out at the bottom, indicating later events exist below

## Layout Variants

### Default (left-aligned)

The default layout places all items on the left with a vertical connector line.

### Compact

Tighter spacing for dense audit logs or activity feeds:

:::preview{title="Compact timeline"}
<x-wirekit::timeline variant="compact">
    <x-wirekit::timeline.item time="09:15">
        <x-slot:title>Login</x-slot:title>
    </x-wirekit::timeline.item>
    <x-wirekit::timeline.item time="09:22">
        <x-slot:title>Updated profile</x-slot:title>
    </x-wirekit::timeline.item>
    <x-wirekit::timeline.item time="09:30">
        <x-slot:title>Logout</x-slot:title>
    </x-wirekit::timeline.item>
</x-wirekit::timeline>
:::

## Timeline Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | string | `'default'` | Layout variant: `'default'`, `'centered'`, `'compact'` |
| `before` | bool | `false` | Show a dashed fade-in line above the first item (indicates earlier events) |
| `after` | bool | `false` | Show a dashed fade-out line below the last item (indicates later events) |
| `scope` | string\|null | `null` | Scoped personalization key |

## Timeline Item Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `time` | string\|null | `null` | Timestamp text (e.g. `'2 hours ago'`, `'09:15'`) |
| `icon` | string\|null | `null` | Semantic icon alias for the dot indicator |
| `variant` | string | `'default'` | Dot color variant: `'default'` (accent), `'success'`, `'warning'`, `'danger'` |
| `intent` | string\|null | `null` | Canonical name for the dot color, accepting the same values as `variant`. Falls back to `variant` when omitted, and wins over it when both are given. |
| `scope` | string\|null | `null` | Scoped personalization key |

### Slots

| Slot | Purpose |
| --- | --- |
| `title` | Event headline (rendered in heading weight) |
| default | Event body/description text |

## Accessibility

- Uses semantic `<ol>` (ordered list) — screen readers announce "list of N items"
- Each event is an `<li>` — natural reading order matches chronological order
- Dot indicators and connector lines are `aria-hidden="true"` — decorative only
- Timestamp uses `<time>` element for machine-readable dates
- All text content is accessible without relying on visual indicators

## Keyboard Interaction

This component is purely presentational and does not respond to keyboard input.

## Pitfalls

- **Don't put more than 50 events in one timeline.** Cognitive overload + DOM weight. Paginate or filter.

## Design Tokens

| Element | Token |
| --- | --- |
| Font family | `--font-wk-sans` |
| Text color | `--color-wk-text` |
| Time text color | `--color-wk-text-muted` |
| Connector line | `--color-wk-border` |
| Default dot | `--color-wk-accent` |
| Success dot | `--color-wk-success` |
| Warning dot | `--color-wk-warning` |
| Danger dot | `--color-wk-danger` |
| Heading weight | `--font-wk-heading-weight` |
| Spacing gap | `--padding-wk-x-md` |
| Dot size | `--size-wk-xs` (fallback: 1.5rem) |

## Customization

Override defaults in `config/wirekit.php`:

```php
'components' => [
    'timeline' => [],
],
```

## Usage & Conventions

> **Prop conventions** — this component uses one or more of the shared semantic prop names (`intent` / `variant` / `tone` / `surface`). See [Prop naming conventions](/extending/prop-naming-conventions) for the canonical vocabulary, alias matrix, and decision tree.

::: info
**Looking for a horizontal timeline?** Reach for [Stepper](/components/stepper) — it lays milestones out along a horizontal (or vertical) axis with connectors and a current-step marker, which is exactly the horizontal-timeline pattern. Timeline is purpose-built for vertical chronological feeds.
:::

## Further Reading

- [WAI-ARIA: Lists](https://www.w3.org/WAI/tutorials/page-structure/content/#lists)
- [MDN: `<ol>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ol)
- [MDN: `<time>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/time)