README.md

The Ultimate Timeline Component for React Applications

Build stunning, interactive timelines with rich media support, accessibility-first design, and comprehensive customization options

Table of Contents

Quick Start

Installation

# Using npm
npm install react-chrono

# Using yarn
yarn add react-chrono

# Using bun (recommended)
bun add react-chrono

Requirements: React 18.2+ or 19+ | Node.js 22+ | TypeScript 4.0+ (optional) | Modern browsers

Basic Usage

Minimal Setup - Your First Timeline

import { Chrono } from 'react-chrono';

const items = [
  { title: 'May 1940', cardTitle: 'Dunkirk', cardDetailedText: 'Allied evacuation from France' },
  { title: 'June 1944', cardTitle: 'D-Day', cardDetailedText: 'Normandy invasion begins' }
];

<Chrono items={items} />

Result Preview:

Common Configurations

<Chrono
  items={items}
  mode="horizontal"
  theme={{ primary: '#0079e6', cardBgColor: '#f5f5f5' }}
/>

const items = [
  {
    title: 'January 2024',
    cardTitle: 'Product Launch',
    cardDetailedText: 'Released version 3.0 with new features',
    media: {
      type: 'IMAGE',
      source: { url: 'https://example.com/launch.jpg' },
      name: 'Product launch event'
    }
  }
];

<Chrono items={items} mode="vertical" />

<Chrono
  items={items}
  mode="alternating"
  animation={{
    slideshow: {
      enabled: true,
      duration: 3000,
      type: 'fade'
    }
  }}
/>

Advanced Configuration with Grouped API ✨

The new grouped API organizes configuration into logical sections:

<Chrono
  items={items}
  mode="alternating"
  
  layout={{
    cardWidth: 450,
    cardHeight: 'auto',  // Automatic sizing based on content
    responsive: { enabled: true, breakpoint: 768 }
  }}
  
  content={{
    alignment: {
      horizontal: 'center',
      vertical: 'center'
    }
  }}
  
  interaction={{
    keyboardNavigation: true,
    pointClick: true,
    autoScroll: true
  }}
  
  display={{
    borderless: false,
    toolbar: { enabled: true, sticky: true }
  }}
  
  animation={{
    slideshow: { enabled: true, duration: 4000, type: 'fade' }
  }}
  
  theme={{
    primary: '#0079e6',
    cardBgColor: '#ffffff',
    cardTitleColor: '#1f2937'
  }}
/>

💡 Try it live: Browse interactive examples in Storybook

Visual Examples

Timeline Modes

React Chrono offers four layout modes, each optimized for specific use cases:

Use Case Guide

<Chrono items={items} mode="vertical" />

<Chrono items={items} mode="horizontal" />

<Chrono items={items} mode="alternating" />

<Chrono items={items} mode="horizontal-all" />

Key Features

Rich Media Integration

const items = [{
  title: 'Event',
  cardTitle: 'Media Example',
  media: {
    type: 'IMAGE',
    source: { url: 'image.jpg' }
  }
}];

<Chrono items={items} />

Interactive Features

<Chrono
  items={items}
  animation={{
    slideshow: {
      enabled: true,
      duration: 3000,
      type: 'fade'
    }
  }}
  interaction={{
    keyboardNavigation: true
  }}
  display={{
    toolbar: {
      enabled: true,
      search: { enabled: true }
    }
  }}
/>

Theming & Customization

<Chrono
  items={items}
  theme={{
    primary: '#0079e6',
    cardBgColor: '#ffffff',
    cardTitleColor: '#1f2937',
    timelineBgColor: '#f5f5f5'
  }}
  darkMode={{ enabled: true }}
/>

Internationalization

<Chrono
  items={items}
  i18n={{
    texts: {
      navigation: {
        first: 'Premier élément',
        next: 'Suivant',
        previous: 'Précédent'
      },
      search: {
        placeholder: 'Rechercher',
        noResults: 'Aucun résultat'
      }
    }
  }}
/>

Advanced Features

// Nested timeline example
const items = [{
  title: 'Major Event',
  cardTitle: 'Period',
  children: <Chrono items={subItems} />
}];

<Chrono items={items} />

Essential Props

React Chrono requires minimal configuration to get started:

📚 Need complete prop documentation? See our comprehensive Props Reference

Migration from v2 to v3

React Chrono v3.0 maintains full backward compatibility - your existing v2.x code will work without changes. However, we recommend migrating to the new grouped API for better maintainability and IDE support.

Quick Migration

v2.x (still works):

<Chrono 
  items={items}
  cardWidth={400}
  disableNavOnKey={false}
  borderLessCards={true}
  slideShow={true}
  slideItemDuration={3000}
  mediaHeight={400}
/>

v3.0 (recommended):

<Chrono
  items={items}
  layout={{ cardWidth: 400 }}
  interaction={{ keyboardNavigation: true }}
  display={{ borderless: true }}
  animation={{
    slideshow: {
      enabled: true,
      duration: 3000
    }
  }}
  media={{ height: 400 }}
/>

Common Prop Mappings

What's New in v3.0

• 🎨 Grouped API - Props organized into logical groups (layout, interaction, content, display, media, animation)
• ⚡ Zero-runtime CSS - Migrated to Vanilla Extract for better performance
• 🌐 i18n Support - 60+ configurable text elements
• 🎭 Google Fonts - Per-element font control
• 🖼️ Fullscreen Mode - Cross-browser fullscreen support
• 📌 Sticky Toolbar - Always-accessible controls

🔗 Complete migration guide: Props Reference

What's New in v3.0

Key Highlights

📋 Full changelog: See CHANGELOG.md for complete details

🔄 Backward Compatible: All v2.x props remain fully supported with automatic mapping to the new grouped API

Development Setup

Prerequisites

• Node.js 22+
• bun (recommended) or npm

Initial Setup

# Clone the repository
git clone https://github.com/prabhuignoto/react-chrono.git
cd react-chrono

# Install dependencies
bun install

Development Commands

# Start development server with hot reload
bun run dev

# Build for production
bun run build

# Run unit tests
bun test

# Lint and format code
bun run clean

Testing Framework

React Chrono uses a comprehensive testing approach:

• Unit Tests: Vitest with @testing-library/react

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Checklist

• Fork the repo and create a feature branch
• Write tests for new features
• Ensure all tests pass: bun run find-bugs
• Follow our code style: bun run clean
• Update documentation if needed
• Submit a pull request

Built With Modern Technologies

Support the Project