# Timeline

> A vertical list of events with a connecting line — activity log, history, changelog.

URL: https://apogee.avaui.dev/docs/timeline
Last updated: 2026-10-15

A vertical list of events with a connecting line — activity log, history, changelog.

Last updated October 15, 2026

```astro
<Timeline items={[
{ title: 'Order placed', time: 'Jan 4', description: 'Order #1234 was created.' },
{ title: 'Shipped', time: 'Jan 5', description: 'Left the warehouse.' },
{ title: 'Delivered', time: 'Jan 7' },
]} />
```

For a stepper with progress state (current / upcoming step), use `Steps` instead.

## Add

```sh
npx @ava-ui/apogee add timeline
```

Depends on `Avatar`.

## Usage

```astro
---
import Timeline from '@/components/apogee/Timeline/Timeline.astro'
---
<Timeline items={[
  { title: 'Order placed', time: 'Jan 4' },
  { title: 'Shipped', time: 'Jan 5' },
]} />
```

## Anatomy

`Timeline` is data-driven (an `items` array); a named slot per item replaces its description with rich content:

-   **List** — an `<ol>` of events.
-   **Connector** — a vertical line (`--border-neutral`, solid or dotted) running between markers; omitted after the last item.
-   **Marker** — a dot outlined in `--border-primary`, or the item’s `avatar`.
-   **Title** — `item.title`, always shown.
-   **Time** — `item.time`, shown next to the title when present (`<time>`, tabular numerals).
-   **Description** — `item.description`, shown below the title when present, or the `item-<index>` slot (quoted text, badges, an attachment).

## API

`@composable` — exposed to Content Editors in AVA. Any other attribute passes through to the root `<ol>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `{ title; time?; datetime?; description?; href?; avatar? }[]` | — | Events, in display order. `datetime` fills `<time datetime>`; `href` makes the title a link; `avatar` (`{ src?, alt?, name?, status? }`) replaces the dot marker. |
| `line` | `'solid' \| 'dotted' \| 'none'` | `'solid'` | The connector between markers. |
| `size` | `'small' \| 'medium'` | `'medium'` | Space between events. |
| `class` | `string` | — | Extra classes on the root `<ol>`, merged last. |

## States

Static, zero-JS — no interactive states.

## Examples

Title only, no time or description:

```astro
<Timeline items={[
{ title: 'Draft created' },
{ title: 'Submitted for review' },
{ title: 'Approved' },
]} />
```

Mixed — some entries with a time and/or description, some without:

```astro
<Timeline items={[
{ title: 'Account created', time: '2024' },
{ title: 'Upgraded to Pro', time: 'Mar 2025', description: 'Switched to annual billing.' },
{ title: 'Invited 3 teammates' },
]} />
```

An activity feed: avatars as markers, a dotted line, links, and rich bodies through `item-<index>` slots.

```astro
<Timeline line="dotted" items={[
{ title: 'Ana Lima', href: '#', time: '2 min ago', datetime: '2026-10-15T09:58', avatar: { name: 'Ana Lima', status: 'online' } },
{ title: 'Marco Ricci', time: '1 h ago', avatar: { name: 'Marco Ricci' } },
]}>
<blockquote slot="item-0">“Can we move the launch to Friday?”</blockquote>
<div slot="item-1" class="flex gap-1"><Badge size="small">Design</Badge></div>
</Timeline>
```

Every `line`:

```astro
<Timeline line="solid" items={…} />
<Timeline line="dotted" items={…} />
<Timeline line="none" items={…} />
```

## Accessibility

Native semantics — an ordered list (`<ol>`/`<li>`) for the events and `<time>` for the timestamp. Markers and the connecting line are `aria-hidden` (decorative). No extra ARIA needed.

## Tokens

| Token | Used for |
| --- | --- |
| `--border-neutral` | Connecting line between markers |
| `--border-primary` | Marker outline |
| `--background-page` | Marker fill |
| `--foreground-neutral` | Title text |
| `--foreground-neutral-faded` | Time + description text |

## Do / Don’t

-   **Do** keep titles short — one line, event-first (“Order shipped”).
-   **Do** order `items` chronologically (oldest first or newest first — consistent with the surrounding page).
-   **Don’t** use `Timeline` for a multi-step form or progress indicator — use `Steps`, which tracks current/upcoming state.
-   **Don’t** pack long paragraphs into `description` — link out to detail instead.

## Content

-   `title` is a short past-tense event statement (“Payment received”), sentence case, no ending period.
-   `time` is a compact date/time string — format it before passing it in (the component renders it verbatim).
-   `description`, when present, is one short sentence of context.

## Related

[

StepsA vertical progress list for onboarding, checkout, and wizard flows.

](https://apogee.avaui.dev/docs/steps)[

ListA styled ordered or unordered list for grouped item content — not for layout rows.

](https://apogee.avaui.dev/docs/list)[

StatDisplays a labelled metric with an optional trend indicator. For dashboards and summary rows.

](https://apogee.avaui.dev/docs/stat)