shadcn-timeline

To use this component, clone the repository, install the dependencies, and run Storybook to view the documentation and examples locally.

# Clone the repository
git clone https://github.com/timDeHof/shadcn-timeline.git

# Install dependencies
npm install

# Run Storybook locally
npm run storybook

The Timeline component acts as a container for TimelineItem components. You can customize the overall size and icon size via the Timeline props.

import { Timeline, TimelineItem } from '@/components/timeline';
import { Check } from 'lucide-react';

export default function Example() {
  return (
    <Timeline>
      <TimelineItem
        date={new Date('2024-01-01')}
        title="Feature Released"
        description="New timeline component is now available"
        icon={<Check />}
        status="completed"
      />
      <TimelineItem
        date={new Date('2024-01-02')}
        title="In Progress"
        description="Working on documentation"
        status="in-progress"
      />
      <TimelineItem
        date={new Date('2024-01-03')}
        title="Upcoming"
        description="Planning future updates"
        status="pending"
      />
    </Timeline>
  );
}

The TimelineTime component is used for displaying and formatting dates.

The Timeline component controls the overall scale of the timeline.

The TimelineItem component represents an individual event within the timeline.

Use the following commands to run the test suite, including Storybook tests and coverage reports.

# Run tests
npm run test

# Run Storybook tests
npm run test-storybook

# Run Storybook tests with coverage
npm run test-storybook:coverage

The shadcn-timeline package exports all core components and layout utilities from its main entry point. You can import the primary Timeline components and layout helpers directly from the package root.

import {
  Timeline,
  TimelineItem,
  TimelineTime,
  TimelineLayout
} from '@/components/timeline';

The timeline component uses specific union types for sizing, status, and color themes to ensure consistency with Shadcn UI patterns.

TimelineSize

• sm
• md
• lg

TimelineStatus

• completed
• in-progress
• pending

TimelineColor

• primary
• secondary
• muted
• accent
• destructive

export type TimelineSize = 'sm' | 'md' | 'lg';
export type TimelineStatus = 'completed' | 'in-progress' | 'pending';
export type TimelineColor = 'primary' | 'secondary' | 'muted' | 'accent' | 'destructive';

The TimelineProps interface defines the configuration options for the main Timeline component. You must provide an items array of TimelineElement objects. You can also customize the global size, animation behavior, iconColor, connectorColor, and CSS className.

import { TimelineElement, TimelineSize, TimelineColor } from './types';

export interface TimelineProps {
  items: TimelineElement[];
  size?: TimelineSize;
  animate?: boolean;
  iconColor?: TimelineColor;
  connectorColor?: TimelineColor;
  className?: string;
}

The TimelineElement interface defines the shape of an individual item within the timeline. Each element requires an id, date, title, and description. Optional properties allow for customization of the visual state and content, including icons, status, color, and loading states.

import { ReactNode } from 'react';
import { TimelineStatus, TimelineColor, TimelineSize } from './types';

export interface TimelineElement {
  id: number;
  date: string;
  title: string;
  description: string;
  icon?: ReactNode | (() => ReactNode);
  status?: TimelineStatus;
  color?: TimelineColor;
  size?: TimelineSize;
  loading?: boolean;
  error?: string;
}