github.com/prabhuignoto/react-chrono @3.3.3 sqlite

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
• Basic Usage
• Visual Examples

Timeline Modes

• Mode Comparison
• Visual Examples
• Use Case Guide

Features

• Key Features
• Rich Media Integration
• Interactive Features
• Theming & Customization
• Internationalization
• Advanced Features

API & Documentation

• Essential Props
• Complete Props Reference
• Migration from v2 to v3
• What's New in v3.0

Development

• Development Setup
• Contributing
• Built With Modern Technologies

Quick Start

⚡ Get started in 30 seconds

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

Horizontal Timeline with Custom Theme

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

Vertical Timeline with Media

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" />

Alternating Timeline with Slideshow

<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

See React Chrono in action

Timeline Modes

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

Use Case Guide

📱 Mobile-First Content → Use Vertical Mode

Perfect for feeds, news timelines, and mobile experiences where scrolling is natural.

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

📊 Historical Narratives → Use Horizontal Mode

Ideal for historical narratives and project phases where the journey matters.

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

💼 Portfolios & Milestones → Use Alternating Mode

Great for portfolios and company milestones with balanced visual rhythm.

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

📈 Dashboards & Comparisons → Use Horizontal All

Perfect for dashboards, comparisons, and seeing the complete picture at once.

<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