Timeline

A flexible timeline component for displaying chronological events, processes, and workflows with support for different orientations, statuses, and custom content.

A versatile timeline component perfect for displaying project workflows, order tracking, user activity, and any chronological sequence of events. Features smooth horizontal scrolling with ScrollArea integration for timeline overflow.

Jan 15, 2024, 09:00 AM

Project Started

Initial project setup and planning phase

Feb 1, 2024, 10:30 AM

Development Phase

Core features implementation in progress

Feb 15, 2024, 02:00 PM

Testing & QA

Quality assurance and testing phase

Mar 1, 2024, 04:00 PM

Launch

Production deployment and launch

function BasicTimelineExample() {
  const items: TimelineItem[] = [
    {
      id: "1",
      title: "Project Started",
      description: "Initial project setup and planning phase",
      timestamp: new Date("2024-01-15T09:00:00"),
      status: "completed",
    },
    {
      id: "2",
      title: "Development Phase",
      description: "Core features implementation in progress",
      timestamp: new Date("2024-02-01T10:30:00"),
      status: "active",
    },
    {
      id: "3",
      title: "Testing & QA",
      description: "Quality assurance and testing phase",
      timestamp: new Date("2024-02-15T14:00:00"),
      status: "pending",
    },
    {
      id: "4",
      title: "Launch",
      description: "Production deployment and launch",
      timestamp: new Date("2024-03-01T16:00:00"),
      status: "pending",
    },
  ];

  return <Timeline items={items} />;
}

Installation

Install following dependencies:

npm install class-variance-authority lucide-react

Copy and paste the following code into your project.

components/ui/timeline.tsx

"use client";

import * as React from "react";
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";
import { ScrollArea } from "@/components/ui/scroll-area";
import {
  Check,
  Clock,
  AlertCircle,
  X,
  Calendar,
  User,
  MapPin,
  MessageSquare,
  Award,
  Briefcase,
  GraduationCap,
  Heart,
} from "lucide-react";

const timelineVariants = cva("relative flex flex-col", {
  variants: {
    variant: {
      default: "gap-4",
      compact: "gap-2",
      spacious: "gap-8",
    },
    orientation: {
      vertical: "flex-col",
      horizontal: "flex-row",
    },
  },
  defaultVariants: {
    variant: "default",
    orientation: "vertical",
  },
});

const timelineItemVariants = cva("relative flex gap-3 pb-2", {
  variants: {
    orientation: {
      vertical: "flex-row",
      horizontal: "flex-col min-w-64 shrink-0",
    },
  },
  defaultVariants: {
    orientation: "vertical",
  },
});

const timelineConnectorVariants = cva("bg-border", {
  variants: {
    orientation: {
      vertical: "absolute left-3 top-9 h-full w-px",
      horizontal: "absolute top-3 left-8 w-full h-px",
    },
    status: {
      default: "bg-border",
      completed: "bg-primary",
      active: "bg-primary",
      pending: "bg-muted-foreground/30",
      error: "bg-destructive",
    },
  },
  defaultVariants: {
    orientation: "vertical",
    status: "default",
  },
});

const timelineIconVariants = cva(
  "flex h-6 w-6 shrink-0 items-center justify-center rounded-full border-2 bg-background text-xs font-medium",
  {
    variants: {
      status: {
        default: "border-border text-muted-foreground",
        completed: "border-primary bg-primary text-primary-foreground",
        active: "border-primary bg-background text-primary animate-pulse",
        pending: "border-muted-foreground/30 text-muted-foreground",
        error: "border-destructive bg-destructive text-destructive-foreground",
      },
    },
    defaultVariants: {
      status: "default",
    },
  },
);

export interface TimelineItem {
  id: string;
  title: string;
  description?: string;
  timestamp?: string | Date;
  status?: "default" | "completed" | "active" | "pending" | "error";
  icon?: React.ReactNode;
  content?: React.ReactNode;
  metadata?: Record<string, any>;
}

export interface TimelineProps extends VariantProps<typeof timelineVariants> {
  items: TimelineItem[];
  className?: string;
  showConnectors?: boolean;
  showTimestamps?: boolean;
  timestampPosition?: "top" | "bottom" | "inline";
}

function getStatusIcon(status: TimelineItem["status"]) {
  switch (status) {
    case "completed":
      return <Check className="h-3 w-3" />;
    case "active":
      return <Clock className="h-3 w-3" />;
    case "pending":
      return <Clock className="h-3 w-3" />;
    case "error":
      return <X className="h-3 w-3" />;
    default:
      return <div className="h-2 w-2 rounded-full bg-current" />;
  }
}

function formatTimestamp(timestamp: string | Date): string {
  if (!timestamp) return "";
  const date = typeof timestamp === "string" ? new Date(timestamp) : timestamp;
  return date.toLocaleDateString("en-US", {
    month: "short",
    day: "numeric",
    year: "numeric",
    hour: "2-digit",
    minute: "2-digit",
  });
}

export function Timeline({
  items,
  className,
  variant,
  orientation = "vertical",
  showConnectors = true,
  showTimestamps = true,
  timestampPosition = "top",
  ...props
}: TimelineProps) {
  const timelineContent = (
    <div
      className={cn(
        timelineVariants({ variant, orientation }),
        orientation === "horizontal" ? "pb-4" : "",
      )}
    >
      {items.map((item, index) => (
        <div
          key={item.id}
          className={cn(timelineItemVariants({ orientation }))}
        >
          {/* Connector Line */}
          {showConnectors && index < items.length - 1 && (
            <div
              className={cn(
                timelineConnectorVariants({
                  orientation,
                  status: item.status,
                }),
              )}
            />
          )}

          {/* Icon */}
          <div className="relative z-10 flex shrink-0">
            <div className={cn(timelineIconVariants({ status: item.status }))}>
              {item.icon || getStatusIcon(item.status)}
            </div>
          </div>

          {/* Content */}
          <div className="flex min-w-0 flex-1 flex-col gap-2">
            {/* Timestamp - Top */}
            {showTimestamps &&
              timestampPosition === "top" &&
              item.timestamp && (
                <time className="text-xs text-muted-foreground">
                  {formatTimestamp(item.timestamp)}
                </time>
              )}

            {/* Title and Inline Timestamp */}
            <div className="flex items-start justify-between gap-2">
              <h3 className="font-medium leading-tight">{item.title}</h3>
              {showTimestamps &&
                timestampPosition === "inline" &&
                item.timestamp && (
                  <time className="shrink-0 text-xs text-muted-foreground">
                    {formatTimestamp(item.timestamp)}
                  </time>
                )}
            </div>

            {/* Description */}
            {item.description && (
              <p className="text-sm text-muted-foreground leading-relaxed">
                {item.description}
              </p>
            )}

            {/* Custom Content */}
            {item.content && <div className="mt-3">{item.content}</div>}

            {/* Timestamp - Bottom */}
            {showTimestamps &&
              timestampPosition === "bottom" &&
              item.timestamp && (
                <time className="text-xs text-muted-foreground">
                  {formatTimestamp(item.timestamp)}
                </time>
              )}
          </div>
        </div>
      ))}
    </div>
  );

  if (orientation === "horizontal") {
    return (
      <ScrollArea
        orientation="horizontal"
        className={cn("w-full", className)}
        {...props}
      >
        {timelineContent}
      </ScrollArea>
    );
  }

  return (
    <div className={className} {...props}>
      {timelineContent}
    </div>
  );
}

// Example Components for Documentation
export function BasicTimelineExample() {
  const items: TimelineItem[] = [
    {
      id: "1",
      title: "Project Started",
      description: "Initial project setup and planning phase",
      timestamp: new Date("2024-01-15T09:00:00"),
      status: "completed",
    },
    {
      id: "2",
      title: "Development Phase",
      description: "Core features implementation in progress",
      timestamp: new Date("2024-02-01T10:30:00"),
      status: "active",
    },
    {
      id: "3",
      title: "Testing & QA",
      description: "Quality assurance and testing phase",
      timestamp: new Date("2024-02-15T14:00:00"),
      status: "pending",
    },
    {
      id: "4",
      title: "Launch",
      description: "Production deployment and launch",
      timestamp: new Date("2024-03-01T16:00:00"),
      status: "pending",
    },
  ];

  return <Timeline items={items} />;
}

export function TimelineVariantsExample() {
  const items: TimelineItem[] = [
    {
      id: "1",
      title: "Task Completed",
      description: "Successfully finished the assigned task",
      status: "completed",
    },
    {
      id: "2",
      title: "In Progress",
      description: "Currently working on this item",
      status: "active",
    },
    {
      id: "3",
      title: "Upcoming",
      description: "Scheduled for later",
      status: "pending",
    },
  ];

  return (
    <div className="space-y-8">
      <div>
        <h3 className="mb-4 text-sm font-medium">Default</h3>
        <Timeline items={items} variant="default" />
      </div>
      <div>
        <h3 className="mb-4 text-sm font-medium">Compact</h3>
        <Timeline items={items} variant="compact" />
      </div>
      <div>
        <h3 className="mb-4 text-sm font-medium">Spacious</h3>
        <Timeline items={items} variant="spacious" />
      </div>
    </div>
  );
}

export function HorizontalTimelineExample() {
  const items: TimelineItem[] = [
    {
      id: "1",
      title: "Planning",
      description: "Project planning and research",
      status: "completed",
    },
    {
      id: "2",
      title: "Design",
      description: "UI/UX design phase",
      status: "completed",
    },
    {
      id: "3",
      title: "Development",
      description: "Core development work",
      status: "active",
    },
    {
      id: "4",
      title: "Testing",
      description: "Quality assurance",
      status: "pending",
    },
    {
      id: "5",
      title: "Launch",
      description: "Production release",
      status: "pending",
    },
  ];

  return <Timeline items={items} orientation="horizontal" />;
}

export function TimelineWithCustomIconsExample() {
  const items: TimelineItem[] = [
    {
      id: "1",
      title: "Account Created",
      description: "Welcome to our platform!",
      timestamp: new Date("2024-01-01T08:00:00"),
      status: "completed",
      icon: <User className="h-3 w-3" />,
    },
    {
      id: "2",
      title: "Profile Updated",
      description: "Personal information has been updated",
      timestamp: new Date("2024-01-02T14:30:00"),
      status: "completed",
      icon: <User className="h-3 w-3" />,
    },
    {
      id: "3",
      title: "First Order Placed",
      description: "Order #12345 has been placed successfully",
      timestamp: new Date("2024-01-03T11:15:00"),
      status: "completed",
      icon: <Briefcase className="h-3 w-3" />,
    },
    {
      id: "4",
      title: "Delivery Scheduled",
      description: "Your order is out for delivery",
      timestamp: new Date("2024-01-04T09:45:00"),
      status: "active",
      icon: <MapPin className="h-3 w-3" />,
    },
  ];

  return <Timeline items={items} />;
}

export function TimelineWithContentExample() {
  const items: TimelineItem[] = [
    {
      id: "1",
      title: "Code Review Completed",
      description: "Pull request #123 has been reviewed",
      timestamp: new Date("2024-01-01T10:00:00"),
      status: "completed",
      content: (
        <div className="rounded-md bg-muted p-3 text-sm">
          <p className="font-medium">Changes approved by John Doe</p>
          <p className="text-muted-foreground">
            3 files changed, +45 -12 lines
          </p>
        </div>
      ),
    },
    {
      id: "2",
      title: "Build Failed",
      description: "CI/CD pipeline encountered errors",
      timestamp: new Date("2024-01-01T11:30:00"),
      status: "error",
      content: (
        <div className="rounded-md bg-destructive/10 p-3 text-sm">
          <p className="font-medium text-destructive">Build #456 failed</p>
          <p className="text-muted-foreground">Syntax error in main.tsx:45</p>
        </div>
      ),
    },
    {
      id: "3",
      title: "Issue Assigned",
      description: "Bug report assigned to development team",
      timestamp: new Date("2024-01-01T15:20:00"),
      status: "active",
      content: (
        <div className="rounded-md bg-primary/10 p-3 text-sm">
          <p className="font-medium">Issue #789: Login form validation</p>
          <p className="text-muted-foreground">
            Priority: High | Assigned to: Jane Smith
          </p>
        </div>
      ),
    },
  ];

  return <Timeline items={items} />;
}

export function ProjectTimelineExample() {
  const items: TimelineItem[] = [
    {
      id: "1",
      title: "Project Kickoff",
      description: "Initial meeting with stakeholders and team members",
      timestamp: new Date("2024-01-15T09:00:00"),
      status: "completed",
      icon: <Briefcase className="h-3 w-3" />,
      content: (
        <div className="space-y-2">
          <div className="flex gap-2 text-sm">
            <span className="font-medium">Attendees:</span>
            <span className="text-muted-foreground">5 team members</span>
          </div>
          <div className="flex gap-2 text-sm">
            <span className="font-medium">Duration:</span>
            <span className="text-muted-foreground">2 hours</span>
          </div>
        </div>
      ),
    },
    {
      id: "2",
      title: "Requirements Gathering",
      description:
        "Detailed analysis of project requirements and specifications",
      timestamp: new Date("2024-01-20T14:00:00"),
      status: "completed",
      icon: <MessageSquare className="h-3 w-3" />,
    },
    {
      id: "3",
      title: "Design Phase",
      description: "UI/UX design and wireframe creation",
      timestamp: new Date("2024-02-01T10:00:00"),
      status: "active",
      icon: <Award className="h-3 w-3" />,
      content: (
        <div className="rounded-md border border-primary/20 bg-primary/5 p-3 text-sm">
          <p className="font-medium">Current Progress: 60%</p>
          <p className="text-muted-foreground">
            Expected completion: Feb 10, 2024
          </p>
        </div>
      ),
    },
    {
      id: "4",
      title: "Development Sprint 1",
      description: "Core functionality implementation",
      timestamp: new Date("2024-02-15T09:00:00"),
      status: "pending",
      icon: <GraduationCap className="h-3 w-3" />,
    },
    {
      id: "5",
      title: "Testing & QA",
      description: "Quality assurance and bug fixes",
      timestamp: new Date("2024-03-01T09:00:00"),
      status: "pending",
      icon: <AlertCircle className="h-3 w-3" />,
    },
  ];

  return <Timeline items={items} variant="spacious" />;
}

export function OrderTrackingTimelineExample() {
  const items: TimelineItem[] = [
    {
      id: "1",
      title: "Order Placed",
      description: "Your order has been successfully placed",
      timestamp: new Date("2024-01-01T10:30:00"),
      status: "completed",
      icon: <Check className="h-3 w-3" />,
    },
    {
      id: "2",
      title: "Payment Confirmed",
      description: "Payment has been processed successfully",
      timestamp: new Date("2024-01-01T10:35:00"),
      status: "completed",
      icon: <Check className="h-3 w-3" />,
    },
    {
      id: "3",
      title: "Order Processing",
      description: "Your order is being prepared for shipment",
      timestamp: new Date("2024-01-01T14:20:00"),
      status: "active",
      icon: <Clock className="h-3 w-3" />,
    },
    {
      id: "4",
      title: "Shipped",
      description: "Your order has been shipped",
      status: "pending",
      icon: <MapPin className="h-3 w-3" />,
    },
    {
      id: "5",
      title: "Delivered",
      description: "Package delivered to your address",
      status: "pending",
      icon: <Heart className="h-3 w-3" />,
    },
  ];

  return <Timeline items={items} timestampPosition="inline" />;
}

export function CompactTimelineExample() {
  const items: TimelineItem[] = [
    {
      id: "1",
      title: "Login",
      timestamp: new Date("2024-01-01T08:30:00"),
      status: "completed",
    },
    {
      id: "2",
      title: "File uploaded",
      timestamp: new Date("2024-01-01T08:35:00"),
      status: "completed",
    },
    {
      id: "3",
      title: "Processing started",
      timestamp: new Date("2024-01-01T08:40:00"),
      status: "active",
    },
    {
      id: "4",
      title: "Processing complete",
      status: "pending",
    },
  ];

  return (
    <Timeline
      items={items}
      variant="compact"
      timestampPosition="inline"
      showTimestamps={true}
    />
  );
}

export function ExtendedHorizontalTimelineExample() {
  const items: TimelineItem[] = [
    {
      id: "1",
      title: "Research",
      description: "Market research and analysis",
      timestamp: new Date("2024-01-01T09:00:00"),
      status: "completed",
      icon: <MessageSquare className="h-3 w-3" />,
    },
    {
      id: "2",
      title: "Planning",
      description: "Project planning and roadmap",
      timestamp: new Date("2024-01-05T10:00:00"),
      status: "completed",
      icon: <Calendar className="h-3 w-3" />,
    },
    {
      id: "3",
      title: "Design",
      description: "UI/UX design and wireframes",
      timestamp: new Date("2024-01-10T11:00:00"),
      status: "completed",
      icon: <Award className="h-3 w-3" />,
    },
    {
      id: "4",
      title: "Prototype",
      description: "Interactive prototype development",
      timestamp: new Date("2024-01-15T14:00:00"),
      status: "completed",
      icon: <Briefcase className="h-3 w-3" />,
    },
    {
      id: "5",
      title: "Development",
      description: "Core feature implementation",
      timestamp: new Date("2024-01-20T09:00:00"),
      status: "active",
      icon: <GraduationCap className="h-3 w-3" />,
    },
    {
      id: "6",
      title: "Testing",
      description: "Quality assurance and testing",
      timestamp: new Date("2024-02-01T10:00:00"),
      status: "pending",
      icon: <AlertCircle className="h-3 w-3" />,
    },
    {
      id: "7",
      title: "Review",
      description: "Stakeholder review and feedback",
      timestamp: new Date("2024-02-05T15:00:00"),
      status: "pending",
      icon: <User className="h-3 w-3" />,
    },
    {
      id: "8",
      title: "Deploy",
      description: "Production deployment",
      timestamp: new Date("2024-02-10T16:00:00"),
      status: "pending",
      icon: <MapPin className="h-3 w-3" />,
    },
    {
      id: "9",
      title: "Launch",
      description: "Product launch and marketing",
      timestamp: new Date("2024-02-15T09:00:00"),
      status: "pending",
      icon: <Heart className="h-3 w-3" />,
    },
  ];

  return <Timeline items={items} orientation="horizontal" variant="spacious" />;
}

export {
  timelineVariants,
  timelineItemVariants,
  timelineConnectorVariants,
  timelineIconVariants,
};

npx hextaui@latest add timeline

Usage

import { Timeline } from "@/components/ui/timeline";

const items = [
  {
    id: "1",
    title: "Event Title",
    description: "Event description",
    timestamp: new Date(),
    status: "completed"
  }
];

<Timeline items={items} />

Examples

Variants

Default

Task Completed

Successfully finished the assigned task

In Progress

Currently working on this item

Upcoming

Scheduled for later

Compact

Task Completed

Successfully finished the assigned task

In Progress

Currently working on this item

Upcoming

Scheduled for later

Spacious

Task Completed

Successfully finished the assigned task

In Progress

Currently working on this item

Upcoming

Scheduled for later

function TimelineVariantsExample() {
  const items: TimelineItem[] = [
    {
      id: "1",
      title: "Task Completed",
      description: "Successfully finished the assigned task",
      status: "completed",
    },
    {
      id: "2",
      title: "In Progress",
      description: "Currently working on this item",
      status: "active",
    },
    {
      id: "3",
      title: "Upcoming",
      description: "Scheduled for later",
      status: "pending",
    },
  ];

  return (
    <div className="space-y-8">
      <div>
        <h3 className="mb-4 text-sm font-medium">Default</h3>
        <Timeline items={items} variant="default" />
      </div>
      <div>
        <h3 className="mb-4 text-sm font-medium">Compact</h3>
        <Timeline items={items} variant="compact" />
      </div>
      <div>
        <h3 className="mb-4 text-sm font-medium">Spacious</h3>
        <Timeline items={items} variant="spacious" />
      </div>
    </div>
  );
}

Horizontal Timeline

Planning

Project planning and research

Design

UI/UX design phase

Development

Core development work

Testing

Quality assurance

Launch

Production release

function HorizontalTimelineExample() {
  const items: TimelineItem[] = [
    {
      id: "1",
      title: "Planning",
      description: "Project planning and research",
      status: "completed",
    },
    {
      id: "2",
      title: "Design",
      description: "UI/UX design phase",
      status: "completed",
    },
    {
      id: "3",
      title: "Development",
      description: "Core development work",
      status: "active",
    },
    {
      id: "4",
      title: "Testing",
      description: "Quality assurance",
      status: "pending",
    },
    {
      id: "5",
      title: "Launch",
      description: "Production release",
      status: "pending",
    },
  ];

  return <Timeline items={items} orientation="horizontal" />;
}

Extended Horizontal Timeline with ScrollArea

Perfect for displaying long processes or workflows with smooth horizontal scrolling.

Jan 1, 2024, 09:00 AM

Research

Market research and analysis

Jan 5, 2024, 10:00 AM

Planning

Project planning and roadmap

Jan 10, 2024, 11:00 AM

Design

UI/UX design and wireframes

Jan 15, 2024, 02:00 PM

Prototype

Interactive prototype development

Jan 20, 2024, 09:00 AM

Development

Core feature implementation

Feb 1, 2024, 10:00 AM

Testing

Quality assurance and testing

Feb 5, 2024, 03:00 PM

Review

Stakeholder review and feedback

Feb 10, 2024, 04:00 PM

Deploy

Production deployment

Feb 15, 2024, 09:00 AM

Launch

Product launch and marketing

function ExtendedHorizontalTimelineExample() {
  const items: TimelineItem[] = [
    {
      id: "1",
      title: "Research",
      description: "Market research and analysis",
      timestamp: new Date("2024-01-01T09:00:00"),
      status: "completed",
      icon: <MessageSquare className="h-3 w-3" />,
    },
    {
      id: "2",
      title: "Planning",
      description: "Project planning and roadmap",
      timestamp: new Date("2024-01-05T10:00:00"),
      status: "completed",
      icon: <Calendar className="h-3 w-3" />,
    },
    {
      id: "3",
      title: "Design",
      description: "UI/UX design and wireframes",
      timestamp: new Date("2024-01-10T11:00:00"),
      status: "completed",
      icon: <Award className="h-3 w-3" />,
    },
    {
      id: "4",
      title: "Prototype",
      description: "Interactive prototype development",
      timestamp: new Date("2024-01-15T14:00:00"),
      status: "completed",
      icon: <Briefcase className="h-3 w-3" />,
    },
    {
      id: "5",
      title: "Development",
      description: "Core feature implementation",
      timestamp: new Date("2024-01-20T09:00:00"),
      status: "active",
      icon: <GraduationCap className="h-3 w-3" />,
    },
    // ... more items
  ];

  return <Timeline items={items} orientation="horizontal" variant="spacious" />;
}

Custom Icons

Jan 1, 2024, 08:00 AM

Account Created

Welcome to our platform!

Jan 2, 2024, 02:30 PM

Profile Updated

Personal information has been updated

Jan 3, 2024, 11:15 AM

First Order Placed

Order #12345 has been placed successfully

Jan 4, 2024, 09:45 AM

Delivery Scheduled

Your order is out for delivery

function TimelineWithCustomIconsExample() {
  const items: TimelineItem[] = [
    {
      id: "1",
      title: "Account Created",
      description: "Welcome to our platform!",
      timestamp: new Date("2024-01-01T08:00:00"),
      status: "completed",
      icon: <User className="h-3 w-3" />,
    },
    {
      id: "2",
      title: "Profile Updated",
      description: "Personal information has been updated",
      timestamp: new Date("2024-01-02T14:30:00"),
      status: "completed",
      icon: <User className="h-3 w-3" />,
    },
    {
      id: "3",
      title: "First Order Placed",
      description: "Order #12345 has been placed successfully",
      timestamp: new Date("2024-01-03T11:15:00"),
      status: "completed",
      icon: <Briefcase className="h-3 w-3" />,
    },
    {
      id: "4",
      title: "Delivery Scheduled",
      description: "Your order is out for delivery",
      timestamp: new Date("2024-01-04T09:45:00"),
      status: "active",
      icon: <MapPin className="h-3 w-3" />,
    },
  ];

  return <Timeline items={items} />;
}

With Custom Content

Jan 1, 2024, 10:00 AM

Code Review Completed

Pull request #123 has been reviewed

Changes approved by John Doe

3 files changed, +45 -12 lines

Jan 1, 2024, 11:30 AM

Build Failed

CI/CD pipeline encountered errors

Build #456 failed

Syntax error in main.tsx:45

Jan 1, 2024, 03:20 PM

Issue Assigned

Bug report assigned to development team

Issue #789: Login form validation

Priority: High | Assigned to: Jane Smith

function TimelineWithContentExample() {
  const items: TimelineItem[] = [
    {
      id: "1",
      title: "Code Review Completed",
      description: "Pull request #123 has been reviewed",
      timestamp: new Date("2024-01-01T10:00:00"),
      status: "completed",
      content: (
        <div className="rounded-md bg-muted p-3 text-sm">
          <p className="font-medium">Changes approved by John Doe</p>
          <p className="text-muted-foreground">3 files changed, +45 -12 lines</p>
        </div>
      ),
    },
    {
      id: "2",
      title: "Build Failed",
      description: "CI/CD pipeline encountered errors",
      timestamp: new Date("2024-01-01T11:30:00"),
      status: "error",
      content: (
        <div className="rounded-md bg-destructive/10 p-3 text-sm">
          <p className="font-medium text-destructive">Build #456 failed</p>
          <p className="text-muted-foreground">Syntax error in main.tsx:45</p>
        </div>
      ),
    },
    {
      id: "3",
      title: "Issue Assigned",
      description: "Bug report assigned to development team",
      timestamp: new Date("2024-01-01T15:20:00"),
      status: "active",
      content: (
        <div className="rounded-md bg-primary/10 p-3 text-sm">
          <p className="font-medium">Issue #789: Login form validation</p>
          <p className="text-muted-foreground">Priority: High | Assigned to: Jane Smith</p>
        </div>
      ),
    },
  ];

  return <Timeline items={items} />;
}

Project Timeline

Perfect for project management and workflow visualization.

Jan 15, 2024, 09:00 AM

Project Kickoff

Initial meeting with stakeholders and team members

Attendees:5 team members

Duration:2 hours

Jan 20, 2024, 02:00 PM

Requirements Gathering

Detailed analysis of project requirements and specifications

Feb 1, 2024, 10:00 AM

Design Phase

UI/UX design and wireframe creation

Current Progress: 60%

Expected completion: Feb 10, 2024

Feb 15, 2024, 09:00 AM

Development Sprint 1

Core functionality implementation

Mar 1, 2024, 09:00 AM

Testing & QA

Quality assurance and bug fixes

function ProjectTimelineExample() {
  const items: TimelineItem[] = [
    {
      id: "1",
      title: "Project Kickoff",
      description: "Initial meeting with stakeholders and team members",
      timestamp: new Date("2024-01-15T09:00:00"),
      status: "completed",
      icon: <Briefcase className="h-3 w-3" />,
      content: (
        <div className="space-y-2">
          <div className="flex gap-2 text-sm">
            <span className="font-medium">Attendees:</span>
            <span className="text-muted-foreground">5 team members</span>
          </div>
          <div className="flex gap-2 text-sm">
            <span className="font-medium">Duration:</span>
            <span className="text-muted-foreground">2 hours</span>
          </div>
        </div>
      ),
    },
    // ... more items
  ];

  return <Timeline items={items} variant="spacious" />;
}

Order Tracking

Great for e-commerce order tracking and delivery status.

Order Placed

Jan 1, 2024, 10:30 AM

Your order has been successfully placed

Payment Confirmed

Jan 1, 2024, 10:35 AM

Payment has been processed successfully

Order Processing

Jan 1, 2024, 02:20 PM

Your order is being prepared for shipment

Shipped

Your order has been shipped

Delivered

Package delivered to your address

function OrderTrackingTimelineExample() {
  const items: TimelineItem[] = [
    {
      id: "1",
      title: "Order Placed",
      description: "Your order has been successfully placed",
      timestamp: new Date("2024-01-01T10:30:00"),
      status: "completed",
      icon: <Check className="h-3 w-3" />,
    },
    {
      id: "2",
      title: "Payment Confirmed",
      description: "Payment has been processed successfully",
      timestamp: new Date("2024-01-01T10:35:00"),
      status: "completed",
      icon: <Check className="h-3 w-3" />,
    },
    {
      id: "3",
      title: "Order Processing",
      description: "Your order is being prepared for shipment",
      timestamp: new Date("2024-01-01T14:20:00"),
      status: "active",
      icon: <Clock className="h-3 w-3" />,
    },
    {
      id: "4",
      title: "Shipped",
      description: "Your order has been shipped",
      status: "pending",
      icon: <MapPin className="h-3 w-3" />,
    },
    {
      id: "5",
      title: "Delivered",
      description: "Package delivered to your address",
      status: "pending",
      icon: <Heart className="h-3 w-3" />,
    },
  ];

  return <Timeline items={items} timestampPosition="inline" />;
}

Compact Timeline

Login

Jan 1, 2024, 08:30 AM

File uploaded

Jan 1, 2024, 08:35 AM

Processing started

Jan 1, 2024, 08:40 AM

Processing complete

function CompactTimelineExample() {
  const items: TimelineItem[] = [
    {
      id: "1",
      title: "Login",
      timestamp: new Date("2024-01-01T08:30:00"),
      status: "completed",
    },
    {
      id: "2",
      title: "File uploaded",
      timestamp: new Date("2024-01-01T08:35:00"),
      status: "completed",
    },
    {
      id: "3",
      title: "Processing started",
      timestamp: new Date("2024-01-01T08:40:00"),
      status: "active",
    },
    {
      id: "4",
      title: "Processing complete",
      status: "pending",
    },
  ];

  return (
    <Timeline 
      items={items} 
      variant="compact" 
      timestampPosition="inline"
      showTimestamps={true}
    />
  );
}

API Reference

Prop	Type	Default
`items?`	`TimelineItem[]`	-
`variant?`	`"default" \| "compact" \| "spacious"`	`"default"`
`orientation?`	`"vertical" \| "horizontal"`	`"vertical"`
`showConnectors?`	`boolean`	`true`
`showTimestamps?`	`boolean`	`true`
`timestampPosition?`	`"top" \| "bottom" \| "inline"`	`"top"`
`className?`	`string`	-

TimelineItem

Prop	Type	Default
`id?`	`string`	-
`title?`	`string`	-
`description?`	`string`	-
`timestamp?`	`string \| Date`	-
`status?`	`"default" \| "completed" \| "active" \| "pending" \| "error"`	`"default"`
`icon?`	`React.ReactNode`	-
`content?`	`React.ReactNode`	-
`metadata?`	`Record<string, any>`	-

Features

Multiple Orientations: Vertical and horizontal timeline layouts
ScrollArea Integration: Smooth horizontal scrolling for long timelines
Status System: Built-in status indicators with appropriate icons and colors
Custom Icons: Support for custom icons per timeline item
Flexible Content: Rich content support with custom React components
Responsive Design: Adapts to different screen sizes
Timestamp Formatting: Automatic timestamp formatting with multiple position options
Connector Lines: Visual connectors between timeline items
Accessibility: Built with proper ARIA attributes and semantic markup
TypeScript: Full TypeScript support with comprehensive type definitions

Status Types

default: Neutral state with gray styling
completed: Finished items with green checkmark
active: Currently active items with pulsing animation
pending: Future items with muted styling
error: Failed items with red error icon

Use Cases

Project Management: Visualize project phases and milestones
Order Tracking: Show order status and delivery progress
User Activity: Display user actions and system events
Process Workflows: Illustrate step-by-step processes
Version History: Show changes and updates over time
Event Logs: Display chronological system or user events

Timeline

Project Started

Development Phase

Testing & QA

Launch

Default

Task Completed

In Progress

Upcoming

Compact

Task Completed

In Progress

Upcoming

Spacious

Task Completed

In Progress

Upcoming

Planning

Design

Development

Testing

Launch

Research

Planning

Design

Prototype

Development

Testing

Review

Deploy

Launch

Account Created

Profile Updated

First Order Placed

Delivery Scheduled

Code Review Completed

Build Failed

Issue Assigned

Project Kickoff

Requirements Gathering

Design Phase

Development Sprint 1

Testing & QA

Order Placed

Payment Confirmed

Order Processing

Shipped

Delivered

Login

File uploaded

Processing started

Processing complete

On this page