# rn-timeline
URL: /docs/native/docyrus/timeline

Vertical timeline component with status indicators, left / alternate / right layouts, animated entrance, and interactive items.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-timeline
```

**Dependencies:**
- [react-native-reanimated](https://www.npmjs.com/package/react-native-reanimated)

## Usage

```tsx
import { Timeline } from '@/components/docyrus-native/timeline';

```

### Alternate Layout

```tsx

```

### Right Layout

Content sits on the left of the line and is right-aligned — useful for RTL-feeling activity feeds.

```tsx

```

### With Item Press

```tsx
,
    },
  ]}
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `TimelineItem[]` | — | Array of timeline events (required) |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Timeline size |
| `variant` | `'default' \| 'outline'` | `'default'` | Dot style variant |
| `lineStyle` | `'solid' \| 'dashed'` | `'solid'` | Global connector line style |
| `layout` | `'left' \| 'alternate' \| 'right'` | `'left'` | Content position relative to the line — `left` = line on the left, `right` = line on the right (content right-aligned), `alternate` = zig-zag |
| `animated` | `boolean` | `false` | Staggered fade-in entrance animation |
| `onItemPress` | `(item: TimelineItem, index: number) => void` | — | Item press handler |
| `onItemClick` | `(item: TimelineItem, index: number) => void` | — | Web-parity alias of `onItemPress` |
| `className` | `string` | — | Container class override |
| `titleClassName` | `string` | — | Title text class override |
| `descriptionClassName` | `string` | — | Description text class override |
| `timeClassName` | `string` | — | Time text class override |

### TimelineItem

| Property | Type | Description |
|----------|------|-------------|
| `title` | `string` | Event title |
| `description` | `string` | Optional description text |
| `time` | `string` | Optional time label |
| `icon` | `ReactNode` | Custom icon (replaces dot) |
| `dotColor` | `string` | Custom dot color (ignored when `status` is set) |
| `status` | `TimelineStatus` | Item status — controls dot icon, line style, and content opacity |
| `content` | `ReactNode` | Rich content slot rendered below description |
| `lineStyle` | `TimelineLineStyle` | Per-item line style override |

## Status

When `status` is set on an item, the dot, line, and content are styled automatically:

| Status | Dot | Line Below | Content |
|--------|-----|------------|---------|
| `completed` | Green circle with check icon | Solid primary | Normal |
| `active` | Primary circle with inner ring | Dashed primary | Normal |
| `pending` | Small muted circle | Dashed muted | Reduced opacity (60%) |
| `error` | Red circle with X icon | Solid red | Normal |

Items without `status` use the `variant` prop for dot styling (backward compatible).

## Type Exports

| Type | Description |
|------|-------------|
| `TimelineProps` | Props for Timeline component |
| `TimelineItem` | Timeline event item type |
| `TimelineSize` | `'sm' \| 'md' \| 'lg'` |
| `TimelineVariant` | `'default' \| 'outline'` |
| `TimelineStatus` | `'completed' \| 'active' \| 'pending' \| 'error'` |
| `TimelineLineStyle` | `'solid' \| 'dashed'` |
| `TimelineLayout` | `'left' \| 'alternate' \| 'right'` |