Timeline

Vertical timeline with status indicators, alternate layout, animated entrance, and custom content slots.

Client Only

Installation

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

Required Packages(1 package)

pnpm add motion

Usage

import { Timeline, type TimelineItem } from "@docyrus/ui/components/timeline";

const items: TimelineItem[] = [
  { 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" },
];

<Timeline items={items} size="md" layout="left" />

Variants

Variant	Description
`default`	Filled dot — `bg-primary`
`outline`	Outlined dot — `border-2 border-primary bg-transparent`

Sizes

Size	Dot	Status Dot	Text
`sm`	`10px`	`20px`	`text-sm` / `text-xs`
`md`	`12px`	`24px`	`text-sm` / `text-sm`
`lg`	`16px`	`28px`	`text-base` / `text-sm`

Layouts

Layout	Description
`left`	Content on the right side of the timeline (default)
`alternate`	Content alternates left and right
`right`	Content on the left side of the timeline

Status Indicators

When TimelineItem.status is set, the dot renders a status icon instead of a plain dot.

Status	Appearance	Line Style
`completed`	Green circle with check icon	Solid primary
`active`	Primary circle with inner ring	Dashed primary
`pending`	Small muted circle (opacity 50%)	Dashed muted
`error`	Red circle with X icon	Solid destructive

Line Styles

Style	Description
`solid`	Continuous line (default for completed/error)
`dashed`	Dashed line (default for active/pending)

Line style can be set globally via lineStyle prop or per-item via TimelineItem.lineStyle.

Custom Content

Each item supports a content slot for arbitrary React nodes below the description:

const items: TimelineItem[] = [
  {
    title: "Shipped",
    status: "active",
    content: (
      <span className="inline-flex rounded-full bg-primary/10 px-2.5 py-0.5 text-xs font-semibold text-primary">
        In Transit
      </span>
    ),
  },
];

Custom Icons

Use the icon slot to render a custom icon instead of the default dot:

import { Rocket } from "lucide-react";

const items: TimelineItem[] = [
  {
    title: "Launch",
    icon: <Rocket className="size-4 text-primary" />,
  },
];

Custom Dot Colors

Use dotColor to override the dot color for individual items (works with both default and outline variants):

const items: TimelineItem[] = [
  { title: "Warning", dotColor: "hsl(var(--warning))" },
  { title: "Success", dotColor: "hsl(var(--success))" },
];

Animation

Set animated to enable staggered fade-in entrance with framer-motion:

<Timeline items={items} animated />

API Reference

TimelineProps

Prop	Type	Default	Description
`items`	`TimelineItem[]`	—	Array of timeline events (required)
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Size of dots, text, and spacing
`variant`	`'default' \| 'outline'`	`'default'`	Dot style (filled or outlined)
`lineStyle`	`'solid' \| 'dashed'`	—	Global line style (overridden by item.lineStyle or status)
`layout`	`'left' \| 'alternate' \| 'right'`	`'left'`	Content placement relative to timeline
`animated`	`boolean`	`false`	Enable staggered entrance animation
`onItemClick`	`(item: TimelineItem, index: number) => void`	—	Click handler for items
`titleClassName`	`string`	—	Custom class for title text
`descriptionClassName`	`string`	—	Custom class for description text
`timeClassName`	`string`	—	Custom class for time text
`className`	`string`	—	Container className

TimelineItem

Property	Type	Default	Description
`title`	`string`	—	Item title (required)
`description`	`string`	—	Item description text
`time`	`string`	—	Time label
`icon`	`ReactNode`	—	Custom icon replacing the dot
`dotColor`	`string`	—	Override dot color
`status`	`'completed' \| 'active' \| 'pending' \| 'error'`	—	Status indicator (replaces dot with icon)
`content`	`ReactNode`	—	Custom content below description
`lineStyle`	`'solid' \| 'dashed'`	—	Per-item line style override

Type Exports

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

Timeline

On this page