Timeline

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

Edit on GitHubEditllms.txt

iOSAndroid

Preview Timeline on your device

Scan with Expo Go

iOS Android

Download Expo Go, then scan the QR code to preview native components.

Installation

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

Required Packages(1 package)

pnpm add react-native-reanimated

Usage

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

<Timeline
  items={[
    { title: 'Order placed', description: 'Confirmed', time: '10:00 AM', status: 'completed' },
    { title: 'Shipped', description: 'On the way', time: '2:00 PM', status: 'active' },
    { title: 'Delivered', time: '—', status: 'pending' },
  ]}
  animated
/>

Alternate Layout

<Timeline
  layout="alternate"
  items={items}
/>

Right Layout

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

<Timeline
  layout="right"
  items={items}
/>

With Item Press

<Timeline
  items={items}
  onItemPress={(item, index) => console.log(item.title, index)}
/>

onItemClick is accepted as a web-parity alias of onItemPress (both fire when both are set), so shared code written against the web Timeline works unchanged.

Custom Content Slot

<Timeline
  items={[
    {
      title: 'Shipped',
      status: 'active',
      content: <Badge variant="outline">In Transit</Badge>,
    },
  ]}
/>

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'`

Timeline

On this page