React Chrono

The Ultimate Timeline Component for React Applications

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

Timeline Modes & Layouts 4 Flexible Modes • Nested Timelines • Responsive	Rich Media & Content Images • Videos • YouTube • Custom Components	Theming & Customization Dark Mode • 36 Properties • Google Fonts
Developer Experience TypeScript • Zero Dependencies • Vanilla Extract	User Experience Slideshow • Search • Keyboard Navigation	Accessibility & i18n WCAG AA • 60+ i18n Elements • Mobile First

Quick Start

API Documentation

Features & Customization

Examples & Development

What's New in v3.0

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

Architectural Overhaul

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

New Features

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

UX Improvements

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

Quality Assurance

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

Developer Experience

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.

Quick Start

Installation

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

Basic Usage

Minimal Setup - Your First Timeline

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

Common Configurations

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

Advanced Configuration with Grouped API ✨

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.

Timeline Modes

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

Horizontal Mode

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

Vertical Mode

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

Alternating Mode

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

Horizontal All

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

Visual Examples

Vertical Mode - Scroll-friendly chronological flow:

Vertical Mode (High Text Density) - Compact view showing detailed information:

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

Dark Mode - Complete theme control with 36 customizable properties:

Horizontal All - Dashboard view showing complete timeline:

Essential Props

React Chrono requires minimal configuration to get started:

Property	Type	Description
`items`	`TimelineItem[]`	Array of timeline data
`mode`	`string`	Layout mode: `'horizontal'` \| `'vertical'` \| `'alternating'` \| `'horizontal-all'`
`theme`	`Theme`	Customize colors and appearance

Need complete prop documentation? See our comprehensive Props Reference

Showcase: What React Chrono Can Do

Rich Media Integration

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.

Interactive Features

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.

Theming & Branding

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.

Complete Internationalization

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

Advanced Architecture

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.

Responsive Design

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.

Migration from v2 to v3

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

Live Examples & Playground

CodeSandbox Examples

Try interactive examples with real-time editing:

Quick Start - Basic vertical timeline for beginners
Product Roadmap - Horizontal timeline with slideshow
Media Gallery - Alternating layout with images
Nested Timeline - Hierarchical project structure
Dark Portfolio - Horizontal-all mode with dark theme
Full Feature Demo - Comprehensive v3.0 showcase

Storybook Documentation

Browse component stories and interactive documentation on Chromatic.

Local Demo Site

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

Development Setup

Prerequisites

Node.js 22+
pnpm (recommended) or npm

Initial Setup

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

# Install dependencies
pnpm install

Development Commands

# 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

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: pnpm run find-bugs
Follow our code style: pnpm run clean
Update documentation if needed
Submit a pull request

Built With Modern Technologies

Core Technologies

React 18+ - Modern React features
TypeScript - Type safety
Vanilla Extract - Zero-runtime CSS-in-JS
Day.js - Date manipulation

Development Tools

Vite - Fast bundling
Vitest - Unit testing
ESLint & Prettier - Code quality

Support the Project

Love React Chrono? Help us grow!

⭐ Star on GitHub | 🐦 Follow on Twitter | 🐛 Report Issues

Made with ❤️ by Prabhu Murthy and contributors

⬆ Back to Top

React Chrono

Timeline Modes & Layouts

Rich Media & Content

Theming & Customization

Developer Experience

User Experience

Accessibility & i18n

Table of Contents

What's New in v3.0

Architectural Overhaul

New Features

UX Improvements

Quality Assurance

Developer Experience

Quick Start

Installation

Basic Usage

Minimal Setup - Your First Timeline

Common Configurations

Advanced Configuration with Grouped API ✨

Timeline Modes

Horizontal Mode

Vertical Mode

Alternating Mode

Horizontal All

Visual Examples

Essential Props

Showcase: What React Chrono Can Do

Rich Media Integration

Interactive Features

Theming & Branding

Complete Internationalization

Advanced Architecture

Responsive Design

Migration from v2 to v3

Live Examples & Playground

CodeSandbox Examples

Storybook Documentation

Local Demo Site

Development Setup

Prerequisites

Initial Setup

Development Commands

Testing Framework

Contributing

Quick Contribution Checklist

Built With Modern Technologies

Support the Project