Shadcn Timeline Component Development

Tim DeHof

Completed work

Frontend Engineer

React

Tailwind CSS

TypeScript

Computer Software

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

Updated ESLint configuration to include TypeScript and Prettier rules for improved code quality.

Added Prettier configuration file for consistent code formatting.

Refactored Jest configuration for better readability and maintainability.

Introduced new sitemap and robots.txt generation for SEO optimization.

Enhanced timeline component with new features, including custom icons and improved layout.

Added new CodeBlock component for displaying code snippets in documentation.

Updated README.md with clearer usage instructions and examples.

Improved overall project structure and organization for better developer experience.

Like this project

Completed work

Posted Sep 28, 2025

Developed a customizable timeline component using React and Tailwind CSS.

Likes

Views