The Ultimate Timeline Component for React Applications
Build stunning, interactive timelines with rich media support, accessibility-first design, and comprehensive customization options
|
4 Flexible Modes • Nested Timelines • Responsive |
Images • Videos • YouTube • Custom Components |
Dark Mode • 36 Properties • Google Fonts |
|
TypeScript • Zero Dependencies • Vanilla Extract |
Slideshow • Search • Keyboard Navigation |
WCAG AA • 60+ i18n Elements • Mobile First |
Quick Start
Timeline Modes
Features
API & Documentation
⚡ Get started in 30 seconds
# Using npm
npm install react-chrono
# Using yarn
yarn add react-chrono
# Using pnpm (recommended)
pnpm add react-chronoRequirements: React 18.2+ or 19+ | Node.js 22+ | TypeScript 4.0+ (optional) | Modern browsers
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:
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:
<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: '#0070f3',
cardBgColor: '#ffffff',
cardTitleColor: '#1f2937'
}}
/>💡 Try it live: Browse interactive examples in Storybook
See React Chrono in action
|
Vertical Mode Scroll-friendly chronological flow |
Alternating Mode Cards alternate left and right |
|
Dark Mode Complete theme control |
Horizontal All Dashboard view showing complete timeline |
|
Timeline with Media Embed YouTube videos and images |
|
React Chrono offers four layout modes, each optimized for specific use cases:
| Mode | Best For | Visual Style |
|---|---|---|
| Vertical | Feeds, news timelines, mobile experiences | Top-to-bottom scroll-friendly layout |
| Horizontal | Historical narratives, project phases | Left-to-right chronological flow |
| Alternating | Portfolios, company milestones | Cards alternate left and right of central axis |
| Horizontal All | Dashboards, comparisons | Shows all timeline items at once |
📱 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" />|
Smart Loading & Performance
|
const items = [{
title: 'Event',
cardTitle: 'Media Example',
media: {
type: 'IMAGE',
source: { url: 'image.jpg' }
}
}];
<Chrono items={items} /> |
|
Slideshow Mode Auto-playing presentations with customizable durations, transition effects, and progress indicators. Keyboard Navigation Full accessibility with arrow keys, Home/End for quick jumps, Escape for modals. Real-time Search Instantly highlights matching content across titles, descriptions, and metadata. |
<Chrono
items={items}
animation={{
slideshow: {
enabled: true,
duration: 3000,
type: 'fade'
}
}}
interaction={{
keyboardNavigation: true
}}
display={{
toolbar: {
enabled: true,
search: { enabled: true }
}
}}
/> |
|
Complete Theme Control
|
<Chrono
items={items}
theme={{
primary: '#0070f3',
cardBgColor: '#ffffff',
cardTitleColor: '#1f2937',
timelineBgColor: '#f5f5f5'
}}
darkMode={{ enabled: true }}
/> |
|
Global Ready
|
<Chrono
items={items}
i18n={{
texts: {
navigation: {
first: 'Premier élément',
next: 'Suivant',
previous: 'Précédent'
},
search: {
placeholder: 'Rechercher',
noResults: 'Aucun résultat'
}
}
}}
/> |
|
Nested Timelines Create multi-level narratives where major events contain detailed sub-timelines. Custom Components Embed fully interactive React components within timeline cards. Responsive Design Fundamentally adapts to each device with smart font sizing and spacing. |
// Nested timeline example
const items = [{
title: 'Major Event',
cardTitle: 'Period',
children: <Chrono items={subItems} />
}];
<Chrono items={items} /> |
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
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.
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 }}
/>| v2.x Prop | v3.0 Prop |
|---|---|
borderLessCards |
display.borderless |
disableNavOnKey |
interaction.keyboardNavigation (inverted) |
timelinePointDimension |
layout.pointSize |
slideShow |
animation.slideshow.enabled |
slideItemDuration |
animation.slideshow.duration |
mediaHeight |
media.height |
parseDetailsAsHTML |
content.allowHTML |
disableToolbar |
display.toolbar.enabled (inverted) |
- 🎨 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
🎉 Major updates and improvements
|
🏗️ Grouped API
Props organized into logical groups ( |
⚡ Performance Complete migration to Vanilla Extract for zero-runtime CSS and improved performance |
🎨 New Features Auto card height, content alignment, Google Fonts, i18n support, fullscreen mode, and more |
📋 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
- 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 cleanReact 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
|
Core Technologies
|
Development Tools |
Love React Chrono? Help us grow!
⭐ Star on GitHub | 🐦 Follow on Twitter | 🐛 Report Issues
Made with ❤️ by Prabhu Murthy and contributors