# Timeline

> Lists what happened to a record, newest first.

A timeline lists the history of a record, newest first, such as the status changes of a clearance or the activity on a contract.

## When to use

- Use it for history: status changes, approvals, uploads, comments.
- Put the newest event on top.
- For recent events, show a relative time ("2 jam lalu") and put the full date in `dateTime` and `title`; older events show the date.
- For the steps still ahead, use a [Stepper](https://design.sosialoka.tech/components/stepper/).

_Live preview of the React and Vue versions: https://design.sosialoka.tech/components/timeline/_

## Anatomy

1. Latest event
2. Event dot
3. Connector
4. Title and time

An ordered list. Each event has a dot, a line to the next event, the time, a title and an optional description.

| Part | Style |
| --- | --- |
| Dot | 10px (`size-2.5`), `rounded-full`. `primary` by default; `success`, `warning`, `destructive` or `muted-foreground` by status. |
| Line | 1px (`w-px`), `border` |
| Time | `text-xs`, `muted-foreground`, in a `<time>` element |
| Title | `text-sm`, `font-medium` |
| Description | `text-sm`, `muted-foreground` |

## Props

| React | Vue | Flutter | Type | Default | Use |
| --- | --- | --- | --- | --- | --- |
| `TimelineItem status` | `:status` | dot color from the theme | `default` \| `success` \| `warning` \| `destructive` \| `muted` | `default` | The dot's color. |
| `TimelineTime dateTime` | `datetime` | `Text` | text | none | The machine-readable time of the event. |
| `TimelineTitle`, `TimelineDescription` | same | `Text` | text | none | What happened. |

`shadcn_ui` has no timeline; the Flutter snippet draws the dots and lines from the theme.

## Code

**React**
```tsx
import { Timeline, TimelineDescription, TimelineItem, TimelineTime, TimelineTitle } from "@/components/ui/timeline"

const events = [
  { status: "success", title: "Disetujui", time: "2026-11-12T14:20", label: "12 Nov 2026, 14.20", text: "Lisensi cover siap dipakai." },
  { status: "default", title: "Ditinjau", time: "2026-11-10T10:05", label: "10 Nov 2026, 10.05", text: "Tim kami memeriksa dokumenmu." },
  { status: "default", title: "Dokumen diterima", time: "2026-11-08T16:40", label: "8 Nov 2026, 16.40", text: "Surat kuasa dan master audio lengkap." },
  { status: "muted", title: "Diajukan", time: "2026-11-05T09:12", label: "5 Nov 2026, 09.12", text: "Kamu mengajukan clearance." },
] as const

export default function TimelineDemo() {
  return (
    <Timeline aria-label="Riwayat clearance Senja di Kota" className="w-full max-w-sm">
      {events.map((e) => (
        <TimelineItem key={e.title} status={e.status}>
          <TimelineTime dateTime={e.time}>{e.label}</TimelineTime>
          <TimelineTitle>{e.title}</TimelineTitle>
          <TimelineDescription>{e.text}</TimelineDescription>
        </TimelineItem>
      ))}
    </Timeline>
  )
}
```

**Vue**
```vue
<script setup lang="ts">
import { Timeline, TimelineDescription, TimelineItem, TimelineTime, TimelineTitle } from "@/components/ui/timeline"

const events = [
  { status: "success", title: "Disetujui", time: "2026-11-12T14:20", label: "12 Nov 2026, 14.20", text: "Lisensi cover siap dipakai." },
  { status: "default", title: "Ditinjau", time: "2026-11-10T10:05", label: "10 Nov 2026, 10.05", text: "Tim kami memeriksa dokumenmu." },
  { status: "default", title: "Dokumen diterima", time: "2026-11-08T16:40", label: "8 Nov 2026, 16.40", text: "Surat kuasa dan master audio lengkap." },
  { status: "muted", title: "Diajukan", time: "2026-11-05T09:12", label: "5 Nov 2026, 09.12", text: "Kamu mengajukan clearance." },
] as const
</script>

<template>
  <Timeline aria-label="Riwayat clearance Senja di Kota" class="w-full max-w-sm">
    <TimelineItem v-for="e in events" :key="e.title" :status="e.status">
      <TimelineTime :datetime="e.time">
        {{ e.label }}
      </TimelineTime>
      <TimelineTitle>{{ e.title }}</TimelineTitle>
      <TimelineDescription>{{ e.text }}</TimelineDescription>
    </TimelineItem>
  </Timeline>
</template>
```

**Flutter**
```dart
// shadcn_ui has no timeline: a column of dots and lines drawn from tokens, newest event on top.
// Each event is one Semantics node, so a screen reader reads title, time and text together.
import 'package:flutter/widgets.dart';
import 'package:shadcn_ui/shadcn_ui.dart';
import 'package:sosialoka_ui/sosialoka_ui.dart';

enum _Status { success, normal, muted }

const _events = [
  (status: _Status.success, title: 'Disetujui', time: '12 Nov 2026, 14.20', text: 'Lisensi cover siap dipakai.'),
  (status: _Status.normal, title: 'Ditinjau', time: '10 Nov 2026, 10.05', text: 'Tim kami memeriksa dokumenmu.'),
  (status: _Status.normal, title: 'Dokumen diterima', time: '8 Nov 2026, 16.40', text: 'Surat kuasa dan master audio lengkap.'),
  (status: _Status.muted, title: 'Diajukan', time: '5 Nov 2026, 09.12', text: 'Kamu mengajukan clearance.'),
];

class TimelineDemo extends StatelessWidget {
  const TimelineDemo({super.key});

  @override
  Widget build(BuildContext context) {
    final theme = ShadTheme.of(context);
    final c = context.sosialoka;
    Color dot(_Status s) => switch (s) {
      _Status.success => c.success,
      _Status.normal => theme.colorScheme.primary,
      _Status.muted => theme.colorScheme.mutedForeground,
    };
    return ConstrainedBox(
      constraints: const BoxConstraints(maxWidth: 384),
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          for (final (index, e) in _events.indexed)
            Semantics(
              label: '${e.title}, ${e.time}. ${e.text}',
              child: ExcludeSemantics(
                child: IntrinsicHeight(
                  child: Row(
                    crossAxisAlignment: CrossAxisAlignment.stretch,
                    children: [
                      SizedBox(
                        width: 16,
                        child: Column(
                          children: [
                            const SizedBox(height: 4),
                            Container(
                              width: 10,
                              height: 10,
                              decoration: BoxDecoration(color: dot(e.status), shape: BoxShape.circle),
                            ),
                            if (index < _events.length - 1)
                              Expanded(child: Container(width: 1, color: theme.colorScheme.border)),
                          ],
                        ),
                      ),
                      const SizedBox(width: 12),
                      Expanded(
                        child: Padding(
                          padding: const EdgeInsets.only(bottom: 20),
                          child: Column(
                            crossAxisAlignment: CrossAxisAlignment.start,
                            children: [
                              Text(e.time, style: theme.textTheme.muted),
                              Text(e.title, style: const TextStyle(fontWeight: FontWeight.w500)),
                              Text(e.text, style: theme.textTheme.muted),
                            ],
                          ),
                        ),
                      ),
                    ],
                  ),
                ),
              ),
            ),
        ],
      ),
    );
  }
}
```

## Install

**React**
```bash
npx shadcn@latest add https://design.sosialoka.tech/r/react/timeline.json
```

**Vue**
```bash
npx shadcn-vue@latest add https://design.sosialoka.tech/r/vue/timeline.json
```

## Accessibility

- It is a list; give it a name with `aria-label`, such as "Riwayat clearance Senja di Kota".
- The title says what happened, so the dot's color is never the only signal.
- The dots and lines are hidden from screen readers. In Flutter, each event is one `Semantics` node with its title, time and text.
