Component

Timeline

A time-ordered list of events with a marker rail — ideal for meeting agendas, activity history, and project progress tracking.

Vertical

The default orientation. Events stack top-to-bottom with a vertical connector between markers.

Today

  • 9:00 AMStand-up

    Daily team sync.

  • 10:30 AMDesign review

    Review new mockups.

  • 2:00 PMEngineering sync
  • 4:00 PMRetro

Horizontal

Pass orientation="horizontal" for a left-to-right layout suited to compact history strips.

  • Jan 3Account created
  • Jan 5Profile completed
  • Jan 10First project
  • Jan 14Invited teammate

With statuses

Set status on each item to colour the marker: done (filled primary), current (ring), upcoming (muted), default (border only).

  • Requirements gathered

    All stakeholders aligned.

  • Design phase

    Mockups approved.

  • Implementation

    In progress — 60% complete.

  • QA & testing
  • Release

Installation

$pnpm add @refraction-ui/react

Usage

tsx
import { Timeline } from '@refraction-ui/react'

const items = [
  { id: '1', title: 'Stand-up',       time: '9:00 AM',  status: 'done'     },
  { id: '2', title: 'Design review',  time: '10:30 AM', status: 'current'  },
  { id: '3', title: 'Engineering sync', time: '2:00 PM', status: 'upcoming' },
]

export function AgendaWidget() {
  return <Timeline items={items} orientation="vertical" />
}

Timeline props

PropTypeDefaultDescription
itemsTimelineItemData[]--Ordered list of events. Each item: `{ id, title, time?, description?, status? }`.
orientation'vertical' | 'horizontal''vertical'Layout direction of the timeline rail.
renderItem(item, index, isLast) => React.ReactNode--Optional render-prop to fully customise individual items.
classNamestring--Additional CSS classes applied to the list element.

TimelineItemData

PropTypeDefaultDescription
idstring--Unique identifier used as the React key.
titlestring--Primary label shown beside the marker.
timestring--Optional timestamp / date string rendered above the title.
descriptionstring--Secondary detail text rendered below the title.
status'done' | 'current' | 'upcoming' | 'default''default'Visual status that controls the marker colour.