Timeline

A vertical timeline component with icons, connectors, status indicators, and stagger animation. Ideal for activity feeds, changelogs, and process steps.

Basic

A vertical timeline for activity feeds, changelogs, version histories, and multi-step processes. Supports icons, status colors, timestamps, and stagger animations.

2 hours ago

Deployed to production

Version 2.4.0 shipped to all regions.

5 hours ago

Pull request merged

feat: add Slider and PinInput components

1 day ago

Code review completed

All feedback addressed and approved.

2 days ago

Issue reported

Bug in NumberInput keyboard navigation.

<Timeline
items={[
  {
    title: "Deployed to production",
    description: "Version 2.4.0 shipped to all regions.",
    timestamp: "2 hours ago",
    status: "success",
    icon: <Rocket className="size-4" />,
  },
  {
    title: "Pull request merged",
    description: "feat: add Slider and PinInput components",
    timestamp: "5 hours ago",
    status: "active",
    icon: <GitMerge className="size-4" />,
  },
  {
    title: "Code review completed",
    description: "All feedback addressed and approved.",
    timestamp: "1 day ago",
    status: "default",
  },
  {
    title: "Issue reported",
    description: "Bug in NumberInput keyboard navigation.",
    timestamp: "2 days ago",
    status: "warning",
  },
]}
/>

<Timelineitems={[  {    title: "Deployed to production",    description: "Version 2.4.0 shipped to all regions.",    timestamp: "2 hours ago",    status: "success",    icon: <Rocket className="size-4" />,  },  {    title: "Pull request merged",    description: "feat: add Slider and PinInput components",    timestamp: "5 hours ago",    status: "active",    icon: <GitMerge className="size-4" />,  },  {    title: "Code review completed",    description: "All feedback addressed and approved.",    timestamp: "1 day ago",    status: "default",  },  {    title: "Issue reported",    description: "Bug in NumberInput keyboard navigation.",    timestamp: "2 days ago",    status: "warning",  },]}/>

Installation

Install the component via the CLI in one command.

npx @work-rjkashyap/unified-ui add timeline

pnpm dlx @work-rjkashyap/unified-ui add timeline

npx @work-rjkashyap/unified-ui add timeline

bunx @work-rjkashyap/unified-ui add timeline

If you haven't initialized your project yet, run npx @work-rjkashyap/unified-ui init first. See the CLI docs for details.

Or install the full package

Use this approach if you prefer to install the entire design system as a dependency instead of copying individual components.

npm install @work-rjkashyap/unified-ui

pnpm add @work-rjkashyap/unified-ui

yarn add @work-rjkashyap/unified-ui

bun add @work-rjkashyap/unified-ui

Anatomy

import {
	Timeline,
	Badge,
	Button,
	TimelineItem,
} from "@work-rjkashyap/unified-ui";

Basic Usage

Pass an items array to Timeline. Each item supports a title, description, timestamp, status, icon, and optional content slot.

<Timeline
  items={[
    {
      title: "Account created",
      description: "Welcome to Unified UI!",
      timestamp: "Jan 1, 2025",
      status: "success",
    },
    {
      title: "First component added",
      description: "Button component published.",
      timestamp: "Jan 3, 2025",
      status: "active",
    },
    {
      title: "Docs published",
      description: "Documentation site launched.",
      timestamp: "Jan 10, 2025",
      status: "default",
    },
  ]}
/>

Status Variants

The status field on each item controls the dot or icon background color and the connector color.

Active step

Currently in progress.

Completed step

Successfully finished.

Warning step

Needs attention.

Error step

Action required.

Pending step

Waiting to start.

Default step

No special state.

<Timeline
items={[
  { title: "Active step",   status: "active"  },
  { title: "Completed",     status: "success" },
  { title: "Warning step",  status: "warning" },
  { title: "Error step",    status: "danger"  },
  { title: "Pending step",  status: "pending" },
  { title: "Default step",  status: "default" },
]}
/>

<Timelineitems={[  { title: "Active step",   status: "active"  },  { title: "Completed",     status: "success" },  { title: "Warning step",  status: "warning" },  { title: "Error step",    status: "danger"  },  { title: "Pending step",  status: "pending" },  { title: "Default step",  status: "default" },]}/>

Status	Dot Color	Icon Background	Use Case
`default`	`--border`	Muted/border	Neutral past events
`active`	`--primary`	Primary + ring	Current step or in-progress
`success`	`--success`	Success	Completed, confirmed events
`warning`	`--warning`	Warning	Needs attention, partially done
`danger`	`--danger`	Danger	Failed, blocked, error state
`pending`	Muted outline	Muted/border	Not yet started

With Icons

Pass any ReactNode as icon to replace the default dot indicator with a styled icon container.

Just now

Deployment complete

All 3 regions updated successfully.

3 min ago

Running tests

CI pipeline in progress — 47 of 112 tests passed.

18 min ago

Build failed

Type error in banner.tsx — line 82.

import { CheckCircle, Clock, AlertCircle } from "lucide-react";

<Timeline
items={[
  {
    title: "Deployment complete",
    description: "All 3 regions updated successfully.",
    timestamp: "Just now",
    status: "success",
    icon: <CheckCircle className="size-4" />,
  },
  {
    title: "Running tests",
    description: "CI pipeline in progress.",
    timestamp: "3 min ago",
    status: "active",
    icon: <Clock className="size-4" />,
  },
  {
    title: "Build failed",
    description: "Type error in banner.tsx — line 82.",
    timestamp: "18 min ago",
    status: "danger",
    icon: <AlertCircle className="size-4" />,
  },
]}
/>

import { CheckCircle, Clock, AlertCircle } from "lucide-react";<Timelineitems={[  {    title: "Deployment complete",    description: "All 3 regions updated successfully.",    timestamp: "Just now",    status: "success",    icon: <CheckCircle className="size-4" />,  },  {    title: "Running tests",    description: "CI pipeline in progress.",    timestamp: "3 min ago",    status: "active",    icon: <Clock className="size-4" />,  },  {    title: "Build failed",    description: "Type error in banner.tsx — line 82.",    timestamp: "18 min ago",    status: "danger",    icon: <AlertCircle className="size-4" />,  },]}/>

Sizes

Small

Event one

First event in the timeline.

Event two

Second event in the timeline.

Event three

Third event in the timeline.

Large

Event one

First event in the timeline.

Event two

Second event in the timeline.

Event three

Third event in the timeline.

<Timeline size="sm" items={items} />
<Timeline size="md" items={items} />
<Timeline size="lg" items={items} />

<Timeline size="sm" items={items} /><Timeline size="md" items={items} /><Timeline size="lg" items={items} />

Size	Dot	Icon Container	Title Font	Description Font
`sm`	8px	24px	12px	12px
`md`	12px	32px	14px	14px
`lg`	16px	40px	16px	14px

Rich Content Slot

Each item accepts a content field for rendering arbitrary content below the description — badges, code snippets, diff previews, etc.

Today

v2.4.0 released

New components and bug fixes.

SliderPinInputNumberInput3 bug fixes

3 days ago

v2.3.1 released

Patch: fix HoverCard animation flicker.

patch

<Timeline
items={[
  {
    title: "v2.4.0 released",
    description: "New components and bug fixes.",
    timestamp: "Today",
    status: "success",
    icon: <Rocket className="size-4" />,
    content: (
      <div className="flex gap-1 flex-wrap mt-1">
        <Badge variant="success" size="sm">Slider</Badge>
        <Badge variant="success" size="sm">PinInput</Badge>
        <Badge variant="info" size="sm">3 bug fixes</Badge>
      </div>
    ),
  },
  {
    title: "v2.3.1 released",
    description: "Patch: fix HoverCard animation flicker.",
    timestamp: "3 days ago",
    status: "default",
  },
]}
/>

<Timelineitems={[  {    title: "v2.4.0 released",    description: "New components and bug fixes.",    timestamp: "Today",    status: "success",    icon: <Rocket className="size-4" />,    content: (      <div className="flex gap-1 flex-wrap mt-1">        <Badge variant="success" size="sm">Slider</Badge>        <Badge variant="success" size="sm">PinInput</Badge>        <Badge variant="info" size="sm">3 bug fixes</Badge>      </div>    ),  },  {    title: "v2.3.1 released",    description: "Patch: fix HoverCard animation flicker.",    timestamp: "3 days ago",    status: "default",  },]}/>

Without Animation

Set animated={false} to disable the stagger slide-in animation entirely.

<Timeline animated={false} items={items} />

Changelog Pattern

A common use case — a versioned changelog feed.

const changelog = [
  {
    title: "v2.4.0 — Major release",
    description: "Added Slider, PinInput, NumberInput, SearchInput, and 12 more components.",
    timestamp: "Dec 2024",
    status: "success" as const,
    icon: <Rocket className="size-4" />,
    content: (
      <div className="flex gap-1 flex-wrap mt-2">
        <Badge variant="success" size="sm">+15 components</Badge>
        <Badge variant="info" size="sm">Motion presets</Badge>
      </div>
    ),
  },
  {
    title: "v2.3.0 — Theme system",
    description: "Introduced DSThemeProvider, CSS custom properties, and dark mode support.",
    timestamp: "Nov 2024",
    status: "success" as const,
  },
  {
    title: "v2.0.0 — Breaking changes",
    description: "Migrated to Tailwind v4, updated token naming convention.",
    timestamp: "Oct 2024",
    status: "warning" as const,
  },
  {
    title: "v1.0.0 — Initial release",
    description: "22 components, token system, Radix UI primitives.",
    timestamp: "Sep 2024",
    status: "default" as const,
  },
];

<Timeline items={changelog} size="md" />

Activity Feed

An activity feed showing user actions with icons and timestamps.

const activity = [
  {
    title: "Sarah left a comment",
    description: `"Looks great! Let's ship it."`,
    timestamp: "2 min ago",
    status: "active" as const,
    icon: <MessageCircle className="size-4" />,
  },
  {
    title: "PR #142 approved",
    description: "feat: add Timeline component",
    timestamp: "15 min ago",
    status: "success" as const,
    icon: <CheckCircle className="size-4" />,
  },
  {
    title: "CI pipeline failed",
    description: "Build error on Node.js 18 target.",
    timestamp: "1 hour ago",
    status: "danger" as const,
    icon: <AlertCircle className="size-4" />,
  },
];

<Timeline items={activity} />

Props

Prop	Type	Default	Description
`items`	`TimelineItemData[]`	—	Required. Array of timeline item data objects.
`align`	`"left" \| "right" \| "alternate"`	`"left"`	Layout alignment of items. `alternate` mirrors odd items.
`size`	`"sm" \| "md" \| "lg"`	`"md"`	Controls dot size, icon container, and typography.
`animated`	`boolean`	`true`	Whether to enable stagger slide-in animation on mount.
`className`	`string`	—	Additional CSS classes on the root container.

TimelineItemData

Field	Type	Description
`id`	`string`	Optional key. Falls back to array index.
`title`	`ReactNode`	Item heading.
`description`	`ReactNode`	Secondary text below the title.
`timestamp`	`ReactNode`	Date/time string rendered above the title in muted text.
`icon`	`ReactNode`	Replaces the dot indicator with a styled icon container.
`status`	`"default" \| "active" \| "success" \| "warning" \| "danger" \| "pending"`	Controls dot/icon background color. Defaults to `"default"`.
`content`	`ReactNode`	Optional rich content rendered below the description.

Motion

Stagger — Items animate in sequence using staggerContainerSlow on the wrapper and slideInFromLeft / slideInFromRight per item (direction depends on align and item index).
Alternating — With align="alternate", even items slide from left and odd items slide from right.
Reduced motion — All animations are bypassed when prefers-reduced-motion is active via useReducedMotion().

Accessibility

The root element is a plain <div> — wrap in a <section> or <ol> context if semantics are needed.
Each TimelineItem is a <div> with a content column — add role="listitem" and a role="list" wrapper for formal list semantics.
Icons and connector lines are aria-hidden="true".
Timestamps use <p> elements — they are naturally announced by screen readers in document order (timestamp → title → description).
All animation triggers are mount-based and non-interactive — no keyboard events are affected.

Design Tokens

Token	Usage
`--primary`	Active dot and icon background
`--success`	Success dot and icon background
`--warning`	Warning dot and icon background
`--danger`	Danger dot and icon background
`--border`	Default dot color and connector line
`--muted`	Pending dot and icon background
`--muted-fg`	Timestamp text color
`--foreground`	Title text color

Timeline

On this page