---
title: "Timeline"
description: "An ordered list of events with date, tone and an optional description. It fits order histories, audits or recent activity, and shows its own text when empty."
kind: block
id: C-061
category: erp
registry: "timeline"
docs: "https://koten.codehive.com.co/blocks/erp/timeline"
markdown: "https://koten.codehive.com.co/md/blocks/erp/timeline.md"
install: "npx shadcn@latest add https://koten.codehive.com.co/r/timeline.json"
language: en
---

# Timeline · 履歴

> Block C-061 in the Koten UI catalog.

An ordered list of events with date, tone and an optional description. It fits order histories, audits or recent activity, and shows its own text when empty.

> Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031).

## Install

Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project.

```bash
# Node
npx shadcn@latest add https://koten.codehive.com.co/r/timeline.json

# Bun
bunx shadcn@latest add https://koten.codehive.com.co/r/timeline.json
```

## Files

- `@/components/patterns/timeline.tsx`
- `@/lib/koten/cn.ts`
- `@/lib/koten/format.ts`
- `@/lib/koten/intl.ts`
- `@/lib/koten/labels.ts`
- `@/lib/koten/provider.tsx`

## Composition

This block composes Koten primitives. Read the source files above before changing its anatomy.

## Examples

### Order events

Three events with date, tone and an optional description.

```tsx
<Timeline
  label="Order history"
  emptyLabel="No events yet"
  events={[
    {
      id: "received",
      time: "Oct 21 12:00",
      dateTime: "2026-10-21T12:00:00.000Z",
      title: "Order received",
      description: "Recorded automatically by the system",
    },
    {
      id: "paid",
      time: "Oct 21 12:25",
      dateTime: "2026-10-21T12:25:00.000Z",
      title: "Payment confirmed",
      tone: "success",
    },
    {
      id: "shipped",
      time: "Oct 22 15:00",
      dateTime: "2026-10-22T15:00:00.000Z",
      title: "Order shipped",
      description: "Tracking KURA-100111",
      tone: "info",
    },
  ]}
/>
```

### Empty list

With no events, the component shows the emptyLabel text.

```tsx
<Timeline
  label="Order history"
  emptyLabel="No events yet"
  events={[]}
/>
```

## Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `events` | `readonly TimelineEvent[]` | `—` | Each event accepts id, time, dateTime, title, description and tone. |
| `label` | `string` | `—` | aria-label of the ordered list. |
| `emptyLabel` | `string` | `—` | Text shown when events is empty. |
| `className` | `string` | `—` | Adds to the component's base classes. |

## Accessibility

- It is an ordered list with aria-label; each event keeps its chronological order in the DOM.
- time uses an ISO dateTime so the date is machine-readable.
- Tone dots are decorative; the event text must describe the change.
- The empty state is a paragraph: if it appears after an action, announce it with aria-live.

## Sources

- Catalog page: https://koten.codehive.com.co/blocks/erp/timeline
- Markdown: https://koten.codehive.com.co/md/blocks/erp/timeline.md
- Repository: https://github.com/codehive-colombia/koten