Top Related Projects
nivo provides a rich set of dataviz components, built on top of the awesome d3 and React libraries
Redefined chart library built with React and D3
A collection of composable React components for building interactive data visualizations
🐯 visx | visualization components
📊 Interactive JavaScript Charts built on SVG
Quick Overview
React-Chrono is a flexible and customizable timeline component for React applications. It allows developers to create interactive timelines with various layouts, themes, and customization options, making it suitable for displaying historical events, project milestones, or any chronological data.
Pros
- Highly customizable with multiple layout options (vertical, horizontal, tree)
- Supports various media types (images, videos, cards) within timeline items
- Responsive design and mobile-friendly
- Well-documented with TypeScript support
Cons
- Limited animation options for timeline transitions
- May require additional styling for complex use cases
- Large bundle size compared to simpler timeline libraries
- Limited built-in accessibility features
Code Examples
- Basic timeline setup:
import { Chrono } from "react-chrono";
const items = [
{ title: "May 1940", cardTitle: "Dunkirk", cardSubtitle: "Men of the British Expeditionary Force (BEF) wade out to a destroyer during the evacuation from Dunkirk." },
{ title: "25 July 1940", cardTitle: "The Battle of Britain", cardSubtitle: "RAF Spitfire pilots scramble for their planes" },
{ title: "June 1941", cardTitle: "Operation Barbarossa", cardSubtitle: "A column of Red Army prisoners of war taken during the first days of the German invasion" },
];
const Timeline = () => (
<Chrono items={items} mode="VERTICAL" />
);
- Customizing timeline appearance:
<Chrono
items={items}
mode="HORIZONTAL"
theme={{
primary: "#0077B6",
secondary: "#48CAE4",
cardBgColor: "#CAF0F8",
titleColor: "#03045E",
}}
cardHeight={200}
slideItemDuration={1000}
/>
- Adding media to timeline items:
const itemsWithMedia = [
{
title: "1969",
cardTitle: "Moon Landing",
cardSubtitle: "Neil Armstrong becomes the first human to step on the Moon",
media: {
type: "IMAGE",
source: {
url: "https://example.com/moon-landing.jpg"
}
}
},
// ... more items
];
<Chrono items={itemsWithMedia} mode="VERTICAL_ALTERNATING" />
Getting Started
-
Install the package:
npm install react-chrono -
Import and use in your React component:
import React from 'react'; import { Chrono } from 'react-chrono'; const MyTimeline = () => { const items = [ { title: "2020", cardTitle: "Event 1", cardSubtitle: "Event 1 Description" }, { title: "2021", cardTitle: "Event 2", cardSubtitle: "Event 2 Description" }, { title: "2022", cardTitle: "Event 3", cardSubtitle: "Event 3 Description" }, ]; return ( <div style={{ width: '500px', height: '400px' }}> <Chrono items={items} mode="VERTICAL" /> </div> ); }; export default MyTimeline;
Competitor Comparisons
nivo provides a rich set of dataviz components, built on top of the awesome d3 and React libraries
Pros of nivo
- Offers a wide variety of chart types and data visualization options
- Highly customizable with extensive documentation and examples
- Built with React and D3, providing powerful and interactive visualizations
Cons of nivo
- Steeper learning curve due to its extensive feature set
- May be overkill for simple timeline or chronological data representation
- Larger bundle size compared to more focused libraries
Code Comparison
nivo example (Bar Chart):
import { ResponsiveBar } from '@nivo/bar'
const MyChart = () => (
<ResponsiveBar
data={data}
keys={['hot dog', 'burger', 'sandwich', 'kebab', 'fries', 'donut']}
indexBy="country"
margin={{ top: 50, right: 130, bottom: 50, left: 60 }}
padding={0.3}
colors={{ scheme: 'nivo' }}
/>
)
react-chrono example (Timeline):
import { Chrono } from "react-chrono";
const MyTimeline = () => (
<Chrono
items={items}
mode="VERTICAL"
slideShow
slideItemDuration={2000}
slideShowInterval={5000}
/>
)
While nivo provides a comprehensive solution for various data visualizations, react-chrono focuses specifically on timeline representations. nivo offers more flexibility but requires more setup, whereas react-chrono provides a simpler API for creating timelines quickly.
Redefined chart library built with React and D3
Pros of recharts
- More comprehensive charting library with various chart types (line, bar, area, etc.)
- Higher GitHub stars and wider community adoption
- Extensive documentation and examples
Cons of recharts
- Steeper learning curve due to more complex API
- Larger bundle size, which may impact performance for simpler use cases
Code Comparison
react-chrono (Timeline component):
<Chrono items={items} mode="VERTICAL" />
recharts (LineChart component):
<LineChart width={400} height={400} data={data}>
<Line type="monotone" dataKey="uv" stroke="#8884d8" />
<CartesianGrid stroke="#ccc" />
<XAxis dataKey="name" />
<YAxis />
</LineChart>
Summary
recharts is a more feature-rich charting library suitable for various data visualization needs, while react-chrono focuses specifically on timeline components. recharts offers greater flexibility but may be overkill for simple timeline requirements. react-chrono provides a more straightforward API for timeline creation but lacks the versatility of recharts for other chart types.
A collection of composable React components for building interactive data visualizations
Pros of Victory
- Comprehensive charting library with a wide range of chart types
- Highly customizable with extensive API and theming options
- Strong community support and regular updates
Cons of Victory
- Steeper learning curve due to its extensive features
- Larger bundle size compared to more focused libraries
- May be overkill for simple timeline or chronological visualizations
Code Comparison
Victory (creating a simple line chart):
import { VictoryChart, VictoryLine, VictoryAxis } from 'victory';
<VictoryChart>
<VictoryLine data={[{x: 1, y: 2}, {x: 2, y: 3}, {x: 3, y: 5}]} />
<VictoryAxis />
</VictoryChart>
react-chrono (creating a simple timeline):
import { Chrono } from "react-chrono";
<Chrono items={[
{ title: "May 1940", cardTitle: "Dunkirk", cardSubtitle: "Men of the British Expeditionary Force (BEF) wade out to..." },
{ title: "May 1940", cardTitle: "Dunkirk", cardSubtitle: "Men of the British Expeditionary Force (BEF) wade out to..." },
]} />
While Victory offers a comprehensive solution for various chart types, react-chrono provides a more focused and easier-to-use option for timeline visualizations. Victory's flexibility comes at the cost of complexity, whereas react-chrono offers a simpler API for its specific use case.
🐯 visx | visualization components
Pros of visx
- More comprehensive data visualization library with a wide range of chart types and components
- Highly customizable and flexible, allowing for complex and interactive visualizations
- Backed by Airbnb, with a larger community and more frequent updates
Cons of visx
- Steeper learning curve due to its extensive API and lower-level components
- Requires more setup and configuration for basic use cases
- May be overkill for simple timeline or chronological visualizations
Code Comparison
react-chrono:
<Chrono items={items} mode="VERTICAL" />
visx:
<XYChart height={300} xScale={{ type: 'band' }} yScale={{ type: 'linear' }}>
<BarSeries dataKey="bar" data={data} />
<Axis orientation="bottom" />
<Axis orientation="left" />
</XYChart>
Summary
react-chrono is a specialized library for creating timeline components, offering a simpler API and easier implementation for chronological data visualization. visx, on the other hand, is a more powerful and versatile data visualization library that can be used for various chart types, including timelines. While react-chrono is more suitable for quick timeline implementations, visx provides greater flexibility and customization options for complex data visualizations across different chart types.
📊 Interactive JavaScript Charts built on SVG
Pros of ApexCharts.js
- Offers a wide variety of chart types and customization options
- Supports responsive and interactive charts out of the box
- Has extensive documentation and a large community
Cons of ApexCharts.js
- Larger file size compared to React Chrono
- May have a steeper learning curve for complex visualizations
- Not specifically designed for timeline or chronological data
Code Comparison
React Chrono:
<Chrono items={items} mode="VERTICAL" />
ApexCharts.js:
var options = {
chart: { type: 'line' },
series: [{ data: [30, 40, 35, 50, 49, 60, 70] }],
xaxis: { categories: [1991, 1992, 1993, 1994, 1995, 1996, 1997] }
};
var chart = new ApexCharts(document.querySelector("#chart"), options);
chart.render();
While React Chrono is specifically designed for creating timelines with a simple API, ApexCharts.js offers more versatility for various chart types but requires more configuration. React Chrono is more focused and easier to use for timeline-specific visualizations, while ApexCharts.js provides broader charting capabilities at the cost of increased complexity.
Convert
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
The Ultimate Timeline Component for React Applications
Build stunning, interactive timelines with rich media support, accessibility-first design, and comprehensive customization options
Timeline Modes & Layouts4 Flexible Modes ⢠Nested Timelines ⢠Responsive |
Rich Media & ContentImages ⢠Videos ⢠YouTube ⢠Custom Components |
Theming & CustomizationDark Mode ⢠36 Properties ⢠Google Fonts |
Developer ExperienceTypeScript ⢠Zero Dependencies ⢠Vanilla Extract |
User ExperienceSlideshow ⢠Search ⢠Keyboard Navigation |
Accessibility & i18nWCAG AA ⢠60+ i18n Elements ⢠Mobile First |
Table of Contents
Quick Start
Timeline Modes
Features
API & Documentation
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
|
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.
<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
|
Smart Loading & Performance
|
|
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. |
|
Theming & Customization
|
Complete Theme Control
|
|
Internationalization
|
Global Ready
|
|
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. |
|
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
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
| 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
What's New in v3.0
ð Major updates and improvements
Key Highlights
|
ðï¸ 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
Development Setup
Prerequisites
- Node.js 22+
- bun (recommended) or npm
Initial Setup
# Clone the repository
git clone https://github.com/prabhuignoto/react-chrono.git
cd react-chrono
# Install dependencies
bun install
Development Commands
# 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 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
|
Development Tools |
Support the Project
Love React Chrono? Help us grow!
â Star on GitHub | ð¦ Follow on Twitter | ð Report Issues
Made with â¤ï¸ by Prabhu Murthy and contributors
Top Related Projects
nivo provides a rich set of dataviz components, built on top of the awesome d3 and React libraries
Redefined chart library built with React and D3
A collection of composable React components for building interactive data visualizations
🐯 visx | visualization components
📊 Interactive JavaScript Charts built on SVG
Convert
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot


