# Timeline
- **Category:** Data Display (`data-display`)
- **Slug:** `data-display/timeline`
- **Status:** stable
- **Platforms:** web
- **Import:** `import { Timeline } from "@protocore/pds";`
- **Docs:** https://pds.protocore.io/components/data-display/timeline
> A vertical event history with square tone markers on a hairline connector — mono timestamp, sans body.
## When to use it
Timeline is for an **ordered history of discrete events** on one entity — an audit trail, a deploy log, a payout's lifecycle. The vertical connector and per-node markers make sequence and status legible at a glance.
It is structure only: it lays out the markers, titles, and timestamps and expects you to fill the slots with value atoms (RelativeTime for the timestamp, RoleChip for the actor, CodeRef for references). Reach for a **DefinitionList** instead when you're showing an entity's *current* fields rather than its history, and for **Steps** when you're guiding a user forward through a process rather than recording what already happened.
## Props
| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `className` | `string` | no | — | — |
| `events` | `TimelineEvent[]` | no | — | Events as data, an alternative to composing `Timeline.Item` children. |
| `style` | `CSSProperties` | no | — | — |
## Examples
### Basics
Pass an `events` array. Each node gets a square tone marker on the connector, a sans title, an optional tone-coloured state word, and a right-aligned timestamp — pass a RelativeTime atom rather than a formatted string.
```tsx
import { Timeline, RelativeTime } from "@protocore/pds";
import type { TimelineEvent } from "@protocore/pds";
// Pass events as data. Each node has a tone marker, a title, an optional
// tone-coloured state word, and a right-aligned timestamp atom.
const events: TimelineEvent[] = [
{
tone: "success",
title: "Settlement batch closed",
state: "settled",
time: ,
},
{
tone: "info",
title: "FX rates refreshed",
time: ,
},
{
tone: "warning",
title: "Retry scheduled for payout po_3390",
state: "pending",
time: ,
},
];
export default function TimelineBasics() {
return ;
}
```
### Composed items
Compose `Timeline.Item` children when a node carries more than a headline — a `detail` line and a trailing meta row of actor chips, references, or deltas. Pass actors as RoleChip and ids as CodeRef so the history reads in the same atoms as the rest of the console.
```tsx
import { Timeline, RoleChip, CodeRef, RelativeTime } from "@protocore/pds";
// Compose Timeline.Item children when nodes carry a detail line and a meta row
// — actor chips, references, deltas — beyond the headline.
export default function TimelineComposed() {
return (
}
detail="Chargeback received from the issuing bank."
>
}
detail="Two-person review completed."
>
}
>
);
}
```
## Usage
**Do**
- Use it for a chronological event history on a single entity (audit, deploy, lifecycle).
- Pass timestamps as a RelativeTime atom and actors as a RoleChip.
- Keep marker tones consistent with Badge/StatusDot so colour means the same everywhere.
- Put supporting references and deltas in the meta row, not the title.
**Don't**
- Don't use it for an entity's current fields — that's a DefinitionList.
- Don't use it as a forward-looking wizard — that's Steps.
- Don't bury the timestamp in the title; it has a dedicated right-aligned slot.
- Don't invent marker tones outside the five semantic ones.
## Accessibility
**Notes**
- Timeline renders an ordered list (`` / `- `), so assistive tech announces the events as a numbered sequence in order.
- The markers and connector are `aria-hidden` decoration — meaning is carried by the title, the state word, and the timestamp text, never by marker colour alone.
- Because each node is static text, keyboard behaviour comes only from interactive atoms you place inside (e.g. a copyable CodeRef in the meta row).
## Related
`status-dot`, `relative-time`, `role-chip`, `definition-list`
---
© Protocore. All rights reserved. Use of the Protocore Design System requires prior written authorization from Protocore (contact@protocore.io). These machine-readable materials must not be ingested into ML-training datasets or derivative design systems. See https://pds.protocore.io/legal/