The Ultimate Timeline Component for React Applications
Build stunning, interactive timelines with rich media support, accessibility-first design, and comprehensive customization options
[](https://www.npmjs.com/package/react-chrono) [](https://www.npmjs.com/package/react-chrono) [](https://bundlephobia.com/package/react-chrono) [](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/)
[](https://dev.azure.com/prabhummurthy/react-chrono/_build/latest?definitionId=7&branchName=master) [](https://coveralls.io/github/prabhuignoto/react-chrono?branch=master) [](https://www.codacy.com/manual/prabhuignoto/react-chrono) [](https://snyk.io/test/github/prabhuignoto/react-chrono)
[](https://prettier.io/)[](https://reactjs.org/)
---
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
|
---
## Table of Contents
Quick Start
- [Installation](#installation)
- [Basic Usage](#basic-usage)
- [Visual Examples](#visual-examples)
Timeline Modes
- [Mode Comparison](#timeline-modes)
- [Visual Examples](#visual-examples)
- [Use Case Guide](#use-case-guide)
Features
- [Key Features](#key-features)
- [Rich Media Integration](#rich-media-integration)
- [Interactive Features](#interactive-features)
- [Theming & Customization](#theming--customization)
- [Internationalization](#internationalization)
- [Advanced Features](#advanced-features)
API & Documentation
- [Essential Props](#essential-props)
- [Complete Props Reference](./PROPS-REFERENCE.md)
- [Migration from v2 to v3](#migration-from-v2-to-v3)
- [What's New in v3.0](#whats-new-in-v30)
Development
- [Development Setup](#development-setup)
- [Contributing](#contributing)
- [Built With Modern Technologies](#built-with-modern-technologies)
---
## Quick Start
**⚡ Get started in 30 seconds**
### Installation
```bash
# 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**
```jsx
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' }
];
```
**Result Preview:**
### Common Configurations
Horizontal Timeline with Custom Theme
```jsx
```
Vertical Timeline with Media
```jsx
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'
}
}
];
```
Alternating Timeline with Slideshow
```jsx
```
### Advanced Configuration with Grouped API ✨
The new grouped API organizes configuration into logical sections:
```jsx
```
> **💡 Try it live**: Browse interactive examples in [Storybook](https://691574b1d6fa2f35b1f812a9-xcdgzhacyn.chromatic.com/?path=/story/layout-modes-vertical--basic)
---
## Visual Examples
**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
|
---
## Timeline Modes
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 |
### Use Case Guide
📱 Mobile-First Content → Use Vertical Mode
Perfect for feeds, news timelines, and mobile experiences where scrolling is natural.
```jsx
```
📊 Historical Narratives → Use Horizontal Mode
Ideal for historical narratives and project phases where the journey matters.
```jsx
```
💼 Portfolios & Milestones → Use Alternating Mode
Great for portfolios and company milestones with balanced visual rhythm.
```jsx
```
📈 Dashboards & Comparisons → Use Horizontal All
Perfect for dashboards, comparisons, and seeing the complete picture at once.
```jsx
```
---
## Key Features
### Rich Media Integration
|
**Smart Loading & Performance**
- Images load only when entering viewport (intersection observers)
- Videos auto-play when timeline items become active
- Automatic responsive sizing and buffering
- Built-in accessibility attributes
|
```jsx
const items = [{
title: 'Event',
cardTitle: 'Media Example',
media: {
type: 'IMAGE',
source: { url: 'image.jpg' }
}
}];
```
|
### Interactive Features
|
**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.
|
```jsx
```
|
### Theming & Customization
|
**Complete Theme Control**
- 36 customizable theme properties
- Dark mode with dedicated properties
- Google Fonts integration with automatic loading
- Per-element typography customization
|
```jsx
```
|
### Internationalization
|
**Global Ready**
- 60+ configurable text elements
- Intelligent fallbacks
- Template strings with variable interpolation
- Full type safety
|
```jsx
```
|
### Advanced Features
|
**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.
|
```jsx
// Nested timeline example
const items = [{
title: 'Major Event',
cardTitle: 'Period',
children:
}];
```
|
---
## 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](./PROPS-REFERENCE.md)
---
## 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):**
```jsx
```
**v3.0 (recommended):**
```jsx
```
### Common Prop Mappings
| 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) |
### 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](./PROPS-REFERENCE.md#-legacy-props-deprecated)
---
## What's New in v3.0
**🎉 Major updates and improvements**
### Key Highlights
|
**🏗️ Grouped API**
Props organized into logical groups (`layout`, `interaction`, `content`, `display`, `media`, `animation`, `style`, `accessibility`, `i18n`) for better IDE autocomplete
|
**⚡ 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](./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
```bash
# Clone the repository
git clone https://github.com/prabhuignoto/react-chrono.git
cd react-chrono
# Install dependencies
bun install
```
### Development Commands
```bash
# 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](./CONTRIBUTING.md) 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
|
**Core Technologies**
- [React 18+](https://reactjs.org/) - Modern React features
- [TypeScript](https://www.typescriptlang.org/) - Type safety
- [Vanilla Extract](https://vanilla-extract.style/) - Zero-runtime CSS-in-JS
- [Day.js](https://day.js.org/) - Date manipulation
|
**Development Tools**
- [Vite](https://vitejs.dev/) - Fast bundling
- [Vitest](https://vitest.dev/) - Unit testing
- [ESLint](https://eslint.org/) & [Prettier](https://prettier.io/) - Code quality
|
---
## Support the Project
**Love React Chrono?** Help us grow!
⭐ [Star on GitHub](https://github.com/prabhuignoto/react-chrono) | 🐦 [Follow on Twitter](https://twitter.com/prabhumurthy2) | 🐛 [Report Issues](https://github.com/prabhuignoto/react-chrono/issues)
Made with ❤️ by [Prabhu Murthy](https://github.com/prabhuignoto) and [contributors](https://github.com/prabhuignoto/react-chrono/graphs/contributors)
---
**[⬆ Back to Top](#react-chrono)**