Timeline

Purpose

Timeline displays a vertical list of events or activities with:

• Icon markers with connecting lines
• Title and subtitle for each item
• Optional badges and trailing content
• Customizable colors per item

When to use

Use Timeline for:

• Activity feeds
• Event history
• Audit logs
• Status change history
• Onboarding progress

Basic usage

import { Timeline, type TimelineItemData } from '@/shared/ui/components/Timeline'
import { Check, Clock, AlertCircle } from 'lucide-react'
import { Badge } from '@/shared/ui/primitives/badge'

const items: TimelineItemData[] = [
  {
    id: '1',
    icon: <Check className="h-4 w-4 text-green-600" />,
    title: 'Order confirmed',
    subtitle: '2 hours ago',
    badge: <Badge variant="success">Completed</Badge>,
    iconContainerClassName: 'bg-green-100',
  },
  {
    id: '2',
    icon: <Clock className="h-4 w-4 text-blue-600" />,
    title: 'Processing payment',
    subtitle: '1 hour ago',
    iconContainerClassName: 'bg-blue-100',
  },
  {
    id: '3',
    icon: <AlertCircle className="h-4 w-4 text-amber-600" />,
    title: 'Awaiting shipment',
    subtitle: 'Just now',
    trailing: <span className="text-xs text-muted-foreground">Pending</span>,
    iconContainerClassName: 'bg-amber-100',
  },
]

export function OrderHistory() {
  return <Timeline items={items} />
}

Props

TimelineProps

Prop	Type	Default	Description
items	TimelineItemData[]	Required	Array of timeline items
className	string	-	Container class
gap	'sm' | 'md' | 'lg'	'md'	Gap between items
showLine	boolean	true	Show connecting line
lineClassName	string	'bg-border'	Default line color class
iconContainerClassName	string	'bg-muted'	Default icon container class

TimelineItemData

Property	Type	Required	Description
id	string	Yes	Unique identifier
icon	ReactNode	Yes	Icon element
title	ReactNode	Yes	Primary text
subtitle	ReactNode	No	Secondary text (timestamp, etc.)
badge	ReactNode	No	Badge next to title
trailing	ReactNode	No	Content on the right side
iconContainerClassName	string	No	Override icon container class
lineClassName	string	No	Override line class for this item

Customization

Per-item styling

const items = [
  {
    id: '1',
    icon: <Check />,
    title: 'Success',
    iconContainerClassName: 'bg-green-100',
    lineClassName: 'bg-green-200',
  },
  {
    id: '2',
    icon: <X />,
    title: 'Failed',
    iconContainerClassName: 'bg-red-100',
    lineClassName: 'bg-red-200',
  },
]

Custom content

const items = [
  {
    id: '1',
    icon: <User />,
    title: (
      <span>
        <strong>John</strong> updated the document
      </span>
    ),
    subtitle: <time dateTime="2024-01-15">Jan 15, 2024</time>,
    trailing: <Button size="sm">View</Button>,
  },
]

Notes

• The connecting line is hidden for the last item
• Icons should be sized appropriately (h-4 w-4 recommended)
• Use iconContainerClassName to set semantic colors per item