Shadcn Timeline Component

A beautiful, accessible, and customizable timeline component built on top of shadcn/ui with React and Tailwind CSS.

The same as shadcn/ui, all components are free to use for personal and commercial.

Just copy and paste to your project and customize to your needs. The code is yours.

Demo & Documentation

• 🔗 View Storybook Documentation
• 🔗 Live Demo

Features

• 🎨 Customizable appearance with different sizes and colors
• ♿️ Fully accessible with ARIA attributes
• 🔄 Loading and error states
• 🎭 Smooth animations with Framer Motion
• 📱 Responsive design
• 🎯 TypeScript support
• 🌐 SSR Compatible
• 📚 Full Storybook documentation and examples

Installation

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

# Install dependencies
npm install

# Run Storybook locally
npm run storybook

Usage

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>
  );
}

Props

Timeline

Prop	Type	Default	Description
size	'sm' | 'md' | 'lg'	'md'	Size of the timeline
iconsize	'sm' | 'md' | 'lg'	'md'	Size of icons

TimelineItem

Prop	Type	Default	Description
date	Date | string | number	-	Date of the event
title	string	-	Title of the event
description	string	-	Description of the event
icon	ReactNode	-	Custom icon
iconColor	'primary' | 'secondary' | 'muted' | 'accent'	'primary'	Color theme of the icon
status	'completed' | 'in-progress' | 'pending'	'completed'	Current status
loading	boolean	false	Show loading state
error	string	-	Show error state

TimelineTime

Prop	Type	Default	Description
date	Date | string | number	-	Date to display
format	string | Intl.DateTimeFormatOptions	-	Date formatting options
className	string	-	Additional CSS classes

Server-Side Rendering

The component is fully SSR compatible and handles hydration properly. Date formatting is handled on the client side to prevent hydration mismatches.

Development

To run Storybook locally:

npm run storybook

This will start Storybook on http://localhost:6006

Testing

Run the test suite:

# Run tests
npm run test

# Run Storybook tests
npm run test-storybook

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

Contributing

• Open an issue if you believe you've encountered a bug.
• Make a Pull request if you want to add a new feature/make quality of life improvements/ fix bugs.

License

MIT