# Timeline

> A chronological list of events, such as an audit trail or deployment history.

Category: Data display · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/timeline

Use Timeline for event histories where order matters: contract audit trails, deployment logs and account activity. Each item has a time, title, optional description and a marker whose tone reflects status. Status is also given in text for screen readers.

## Import

```tsx
import { Timeline, TimelineItem } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Audit trail

```tsx
import { Timeline, TimelineItem } from '@bindshq/stance-react';

export function Basic() {
  return (
    <Timeline aria-label="Contract MSA-2026-014 history">
      <TimelineItem
        title="Contract created"
        time="3 Nov, 10:02"
        dateTime="2026-11-03T10:02"
        description="Drafted by Priya Raman from the MSA template."
      />
      <TimelineItem
        title="Sent for signature"
        time="4 Nov, 14:30"
        dateTime="2026-11-04T14:30"
        tone="accent"
      />
      <TimelineItem
        title="Signed by Northwind Ltd"
        time="6 Nov, 09:12"
        dateTime="2026-11-06T09:12"
        tone="success"
        statusLabel="Completed"
      />
    </Timeline>
  );
}
```

### Icons and tones

```tsx
import { Icon, Timeline, TimelineItem } from '@bindshq/stance-react';

export function WithIcons() {
  return (
    <Timeline aria-label="Deployment log">
      <TimelineItem
        icon={<Icon name="upload" />}
        tone="accent"
        title="Sales 2026 published"
        time="09:12"
      />
      <TimelineItem
        icon={<Icon name="check" />}
        tone="success"
        statusLabel="Succeeded"
        title="Deployed to 48 mailboxes"
        time="09:20"
        description="Exchange relay accepted every user."
      />
      <TimelineItem
        icon={<Icon name="alert-triangle" />}
        tone="warning"
        statusLabel="Warning"
        title="2 users missing job titles"
        time="09:20"
      />
      <TimelineItem
        icon={<Icon name="x" />}
        tone="danger"
        statusLabel="Failed"
        title="tomas@binds.si failed"
        time="09:21"
        description="Mailbox not found."
      />
    </Timeline>
  );
}
```

### Alternating

On screens 768px and wider, items alternate sides.

```tsx
import { Timeline, TimelineItem } from '@bindshq/stance-react';

export function Alternate() {
  return (
    <Timeline alternate aria-label="Onboarding">
      <TimelineItem title="Organisation created" time="Mon" tone="accent" />
      <TimelineItem title="Exchange connected" time="Tue" tone="success" statusLabel="Done" />
      <TimelineItem title="Templates assigned" time="Wed" />
      <TimelineItem title="First deployment" time="Thu" />
    </Timeline>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Timeline | `alternate` | `boolean` | `false` | Alternate items left/right on wide screens. |
| Timeline | `density` | `'sm' \| 'md'` | `'md'` | Marker size and spacing. |
| TimelineItem | `title` (required) | `ReactNode` | None | What happened. |
| TimelineItem | `time` | `ReactNode` | None | Human-readable time. |
| TimelineItem | `dateTime` | `string` | None | Machine-readable time for <time>. |
| TimelineItem | `description` | `ReactNode` | None | Supporting detail. |
| TimelineItem | `icon` | `ReactNode` | None | Icon inside the marker; a dot otherwise. |
| TimelineItem | `tone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Marker colour. |
| TimelineItem | `statusLabel` | `string` | None | Status announced to screen readers, e.g. "Failed". |

## Accessibility

- Renders an ordered list, so position and count are announced.
- Times use <time datetime> for machine readability.
- Markers are decorative. Pass statusLabel so status is never conveyed by colour alone.

## Guidelines

**Do**

- Order newest first for activity feeds and oldest first for processes.

**Don’t**

- Use Timeline for steps the user must complete; use Stepper.

## Related

- https://stanceui.com/components/stepper
- https://stanceui.com/components/list