The Ultimate Timeline Component for React Applications

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

React Chrono v3.0 represents a complete evolution of the timeline component with architectural improvements and powerful new features:

• Grouped Configuration API - Props organized into logical groups (layout, interaction, content, display, media, animation, style, accessibility, i18n) for intuitive configuration and better IDE autocomplete
• Vanilla Extract Migration - Complete migration from styled-components to Vanilla Extract for zero-runtime CSS, improved performance, and type-safe styling
• Unified Context System - Streamlined from multiple contexts to a single optimized provider, reducing complexity and improving performance

• Auto Card Height - cardHeight: 'auto' for content-based sizing
• Content Alignment - Horizontal and vertical alignment control within cards
• Google Fonts - Dynamic font loading with per-element customization
• i18n Support - 40+ configurable text elements for global applications
• Fullscreen Mode - Cross-browser support with keyboard shortcuts
• Enhanced Dark Mode - 36 theme properties for complete customization
• Sticky Toolbar - Optional sticky positioning with configurable placement
• Borderless Cards - Minimal card variant for modern designs
• Advanced Search - Customizable search input sizing and positioning

• Responsive Popovers - Smart positioning that adapts to fullscreen mode
• Enhanced Navigation - Keyboard support with improved focus management
• Text Density - Compact and detailed view options for different use cases
• Smooth Animations - Refined transitions and interactions

• Component Testing - Isolated tests with visual regression checks
• Integration Tests - Build output validation and cross-browser testing

• TypeScript First - Full type definitions and IntelliSense support
• Comprehensive Docs - Props reference and migration guides
• Interactive Examples - Live CodeSandbox and Storybook demos

All v2.x props remain fully supported with automatic mapping to the new grouped API, ensuring seamless upgrades without breaking changes.

Get started with React Chrono in seconds:

# Using npm
npm install react-chrono

# Using yarn
yarn add react-chrono

# Using pnpm (recommended)
pnpm add react-chrono

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

Browse interactive examples in Storybook.

Get started with just two lines of code:

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

Horizontal Timeline with Custom Theme

<Chrono
  items={items}
  mode="horizontal"
  theme={{ primary: '#0070f3', 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'
    }
  }}
/>

The new grouped API organizes configuration into logical sections for better discoverability and maintainability:

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

  layout={{
    cardWidth: 450,
    cardHeight: 'auto',  // NEW: Automatic sizing based on content
    responsive: { enabled: true, breakpoint: 768 }
  }}

  content={{
    alignment: {  // NEW: Control 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: '#0070f3',
    cardBgColor: '#ffffff',
    cardTitleColor: '#1f2937'
  }}
/>

Quick Start Examples by Use Case:

// Corporate Timeline
<Chrono items={milestones} mode="horizontal" theme={{ primary: '#1a73e8' }} />

// Project Roadmap
<Chrono
  items={tasks}
  mode="vertical"
  display={{ toolbar: { enabled: true, sticky: true } }}
/>

// Photo Timeline with Auto Height
<Chrono
  items={memories}
  mode="alternating"
  layout={{ cardHeight: 'auto' }}  // Cards size automatically to content
  media={{ height: 300, fit: 'cover' }}
/>

// Documentation Timeline
<Chrono
  items={releases}
  mode="vertical"
  content={{ allowHTML: true, readMore: true }}
/>

🚀 Migration Made Easy: All existing v2.x props work alongside the new grouped API for seamless upgrades.

React Chrono offers four thoughtfully designed layout modes, each optimized for specific content types and user experiences:

Left-to-right chronological flow. Ideal for historical narratives and project phases where the journey matters.

Top-to-bottom scroll-friendly layout. Perfect for feeds, news timelines, and mobile experiences.

Cards alternate left and right of a central axis. Great for portfolios and company milestones with balanced visual rhythm.

Shows all timeline items at once. Perfect for dashboards, comparisons, and seeing the complete picture.

Vertical Mode - Scroll-friendly chronological flow:

Alternating Mode - Cards alternate left and right with visual balance:

Dark Mode - Complete theme control with customizable properties:

Horizontal All - Dashboard view showing complete timeline:

Timeline with Media - Embed youtube videos and images in timeline items:

React Chrono requires minimal configuration to get started:

Need complete prop documentation? See our comprehensive Props Reference

Images load intelligently using intersection observers - only when entering the viewport - ensuring fast initial loads even with dozens of high-resolution photos. Videos auto-play when timeline items become active, creating cinematic storytelling experiences. The component handles responsive sizing, buffering states, accessibility attributes, and performance optimization automatically.

Slideshow Mode: Auto-playing presentations with customizable durations, transition effects, and progress indicators - perfect for kiosks and guided storytelling.

Keyboard Navigation: Full accessibility with arrow keys for navigation, Home/End for quick jumps to first/last items, and Escape for closing modals. Smooth animations respect user motion preferences.

Real-time Search: Instantly highlights matching content across titles, descriptions, and metadata, helping users find specific events without losing context.

Adapt to any visual identity with a comprehensive theming system. Dark mode is a first-class feature with dedicated properties for shadows, glows, and interaction states. Google Fonts integration handles loading optimization and fallback strategies automatically, making typography customization effortless.

Customize every piece of user-facing text for any language or locale. The i18n system uses intelligent fallbacks - configure only what you need to change. Template strings support variable interpolation with full type safety.

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

Nested Timelines: Create multi-level narratives where major events contain detailed sub-timelines - ideal for historical periods, project phases, or biographical chapters.

Custom Components: Embed fully interactive React components within timeline cards - data visualizations, interactive maps, widgets, or custom UI elements.

Fundamentally adapts to each device: precision hover states and multi-column layouts on desktop, optimized touch targets on tablets, and content-prioritized interfaces on mobile with smart font sizing and spacing.

Upgrading is seamless with full backward compatibility:

// ✅ Both syntaxes work
<Chrono 
  cardWidth={400}           // Legacy prop
  disableNavOnKey={false}   // Legacy prop
  theme={{ primary: '#blue' }}
/>

// 🚀 New grouped API (recommended)
<Chrono
  layout={{ cardWidth: 400 }}
  interaction={{ keyboardNavigation: true }}
  theme={{ primary: '#blue' }}
/>

🔗 Complete migration guide: Props Reference

Explore our comprehensive demo site with interactive examples. Run pnpm run dev locally to access:

• All timeline layout modes (horizontal, vertical, alternating, horizontal-all)
• Dark mode theming examples
• Google Fonts integration demos
• Internationalization samples
• Media-rich timelines
• Custom content examples
• Nested timeline structures

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

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

# Install dependencies
pnpm install

# Start development server with hot reload
pnpm run dev

# Build for production
pnpm run build

# Run unit tests
pnpm test

# Lint and format code
pnpm run clean

React Chrono uses a comprehensive testing approach:

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

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

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