# React Native Timeline (Pro)

> A React Native timeline for iOS, Android and the web: events along a line with status markers (done, in progress, upcoming, failed), icons, times on either side, alternating sides, cards, day headings, Show more, and a horizontal mode. Accessible, animated, themeable.

# Timeline Pro

Events in order along a line: a project's history, a shipment's scans, an incident's updates. Each marker shows its step's status, done, in progress (with a gentle pulse), upcoming or failed, and the line fills up to the step in progress. Times sit beside the title or across the line. Long histories fold behind Show more, and dated ones can be headed by day. Each entry is read as one sentence with its status.

```tsx
import { Timeline } from '@patine-ui/pro';
```

```tsx live full
import { Timeline } from '@patine-ui/pro';

const hoursAgo = (h) => new Date(Date.now() - h * 3600000);
const steps = [
  { key: 'placed', title: 'Order placed', description: 'Paid with Visa •••• 4242', time: hoursAgo(50), icon: 'receipt' },
  { key: 'packed', title: 'Packed', description: 'Warehouse B, Newark', time: hoursAgo(26), icon: 'package' },
  { key: 'shipped', title: 'Shipped', description: 'UPS Ground', time: hoursAgo(20), icon: 'truck' },
  { key: 'out', title: 'Out for delivery', icon: 'navigation' },
  { key: 'delivered', title: 'Delivered', icon: 'home' },
];

export default function Example() {
  return <Timeline items={steps} current="out" line="dashed" style={{ width: 380 }} />;
}
```

## Example: an incident report

A status page's incident: updates newest first, each with its time, the current state marked, and older updates folded behind Show more.

```tsx live
import { View } from 'react-native';
import { Badge, HStack, Text } from 'patine-ui';
import { Timeline } from '@patine-ui/pro';

const minutesAgo = (m: number) => new Date(Date.now() - m * 60000);
const UPDATES = [
  { key: 'monitoring', title: 'Monitoring', description: 'Payments are processing normally. We’re watching error rates.', time: minutesAgo(12), icon: 'activity' },
  { key: 'fix', title: 'Fix deployed', description: 'Rolled back the connection pool change.', time: minutesAgo(31), icon: 'refreshCcw' },
  { key: 'identified', title: 'Identified', description: 'A config change cut database connections in half.', time: minutesAgo(48), icon: 'search' },
  { key: 'investigating', title: 'Investigating', description: 'Some card payments time out.', time: minutesAgo(63), icon: 'alert' },
  { key: 'detected', title: 'Alert fired', description: 'Error rate on /charges above 5%.', time: minutesAgo(66), icon: 'bell' },
];

export default function Example() {
  return (
    <View style={{ width: '100%', maxWidth: 440, gap: 12 }}>
      <HStack gap="sm" align="center">
        <Text weight="semibold">Card payments failing</Text>
        <Badge variant="warning">Monitoring</Badge>
      </HStack>
      <Timeline items={UPDATES} current="monitoring" maxVisible={3} />
    </View>
  );
}
```

## Status

Set `current` to a step's key: steps before it are done, it's in progress, the rest are upcoming. Or give each item its own `status`: `'complete'`, `'current'`, `'upcoming'`, `'error'` or `'warning'`. `color` overrides a marker's color with a theme color name or any CSS color.

## Markers and lines

`marker` is `'dot'`, `'ring'`, `'icon'` (the item's `icon`, or a check, cross or alert by status) or `'number'`. `markerSize` sets the icon and number markers' diameter. `line` is `'solid'`, `'dashed'` (only the stretch still to come is dashed) or `'none'`.

```tsx live full
import { Timeline } from '@patine-ui/pro';

const steps = [
  { key: 'a', title: 'Create your account' },
  { key: 'b', title: 'Verify your email' },
  { key: 'c', title: 'Connect a bank', status: 'error', description: 'The bank declined the link. Try again.' },
  { key: 'd', title: 'Start investing' },
];

export default function Example() {
  return (
    <View style={{ flexDirection: 'row', gap: 32, flexWrap: 'wrap' }}>
      <Timeline items={steps} current="c" marker="number" style={{ width: 260 }} />
      <Timeline items={steps} current="c" marker="ring" line="dashed" density="compact" style={{ width: 260 }} />
    </View>
  );
}
```

## Variants

`'default'` puts the time beside the title, `'opposite'` on the other side of the line, `'alternate'` puts entries on both sides by turns, and `'card'` puts each entry in a card.

```tsx live full
import { Timeline } from '@patine-ui/pro';

const releases = [
  { key: '3', title: 'v3.0', description: 'Blocks, a new design system', time: 'Nov 2026', icon: 'rocket' },
  { key: '2', title: 'v2.0', description: 'Charts and the AI chat', time: 'Jun 2026', icon: 'barChart' },
  { key: '1', title: 'v1.0', description: 'First release', time: 'Jan 2026', icon: 'sparkles' },
];

export default function Example() {
  return (
    <View style={{ gap: 32, width: 520 }}>
      <Timeline items={releases} variant="alternate" />
      <Timeline items={releases} variant="opposite" />
      <Timeline items={releases} variant="card" marker="dot" />
    </View>
  );
}
```

## Days, relative times and Show more

`groupByDay` heads each day's entries ("Today", "Yesterday", "Mon, Mar 3"). `timeFormat` reads dated times as `'time'`, `'date'`, `'datetime'` or `'relative'` ("2 hours ago"). `maxVisible` folds the rest behind "Show N more"; `expanded` and `onExpandedChange` control it. `reverse` puts the newest first.

```tsx live full
import { Timeline } from '@patine-ui/pro';

const minutesAgo = (m) => new Date(Date.now() - m * 60000);
const incident = [
  { key: '1', title: 'Resolved', description: 'Error rates are back to normal.', time: minutesAgo(5), status: 'complete', icon: 'checkCircle', color: 'success' },
  { key: '2', title: 'Monitoring', description: 'A fix has been deployed.', time: minutesAgo(40), icon: 'eye' },
  { key: '3', title: 'Identified', description: 'A bad config push on the API gateway.', time: minutesAgo(70), icon: 'search', color: 'warning' },
  { key: '4', title: 'Investigating', description: 'Elevated 5xx errors on the API.', time: minutesAgo(60 * 26), icon: 'alert', color: 'danger' },
  { key: '5', title: 'Scheduled maintenance', time: minutesAgo(60 * 50), icon: 'settings' },
];

export default function Example() {
  return <Timeline items={incident} groupByDay timeFormat="relative" maxVisible={3} style={{ width: 400 }} />;
}
```

## Across

`orientation="horizontal"` lays the steps across in a row that scrolls sideways.

```tsx live full
import { Timeline } from '@patine-ui/pro';

const steps = [
  { key: 'cart', title: 'Cart', icon: 'cart' },
  { key: 'ship', title: 'Shipping', icon: 'truck' },
  { key: 'pay', title: 'Payment', icon: 'card' },
  { key: 'done', title: 'Review', icon: 'checkCircle' },
];

export default function Example() {
  return <Timeline items={steps} current="pay" orientation="horizontal" style={{ width: 600 }} />;
}
```

## Your own markers and content

`renderMarker` and `renderContent` get `{ item, index, status, time, color, theme }`; item `content` adds any node under the description.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `TimelineItem[]` | — | `{ key, title, description?, time?, icon?, status?, color?, content?, disabled? }` |
| `current` | `string` | — | The step in progress: before it done, after it upcoming. |
| `variant` | `'default'` \| `'opposite'` \| `'alternate'` \| `'card'` | `'default'` | |
| `orientation` | `'vertical'` \| `'horizontal'` | `'vertical'` | |
| `marker` | `'dot'` \| `'ring'` \| `'icon'` \| `'number'` | `'icon'` with icons, else `'dot'` | |
| `markerSize` | `number` | the design's | |
| `line` | `'solid'` \| `'dashed'` \| `'none'` | `'solid'` | |
| `reverse` | `boolean` | `false` | Newest first. |
| `groupByDay` | `boolean` | `false` | Day headings. |
| `timeFormat` | `'time'` \| `'date'` \| `'datetime'` \| `'relative'` | `'datetime'` | |
| `locale` / `hour12` / `now` | | | |
| `maxVisible` / `expanded` / `defaultExpanded` / `onExpandedChange` | | | Fold long histories. |
| `onItemPress` | `(item) => void` | — | |
| `renderMarker` / `renderContent` | `(info) => ReactNode` | — | |
| `loading` / `error` / `onRetry` / `emptyTitle` / `emptyDescription` / `renderEmpty` | | | States. |
| `density` / `animate` / `labels` / `design` / `theme` / `accessibilityLabel` / `style` | | | |
