A highly customizable, visually stunning, and interactive timeline component for React. Perfect for historical timelines, product roadmaps, project schedules, and data visualization.
- Interactive: Smooth zoom and pan via mouse wheel or drag.
- Mobile Optimized: Adaptive layout, touch-friendly controls, and optimized tooltips.
- Integrated Search: Fast fuzzy search with suggestions and keyboard shortcuts (⌘K / Ctrl+K).
- Deep Theming: Fully customizable via CSS variables and React props.
- Dark Mode: Native support with refined transitions.
- Extensible: Custom renderers for icons, search suggestions, and detail modals.
- Data Density: Integrated histogram in the scrubber to visualize data distribution.
- Performant: Optimized rendering for large datasets using virtualization principles.
import { PanoramaTimeline } from "panorama-timeline";
import "panorama-timeline/dist/panorama-timeline.css";
const events = [
{
id: "1",
time: new Date(1969, 6, 20),
date: "July 20, 1969",
title: "Moon Landing",
description: "Apollo 11 lands the first humans on the Moon.",
category: "space",
icon: "🚀"
}
];
const categories = [
{ id: "space", label: "Space Exploration", color: "#3b82f6" }
];
function App() {
return (
<div style={{ height: "600px", width: "100%" }}>
<PanoramaTimeline
events={events}
categories={categories}
/>
</div>
);
}| Prop | Type | Default | Description |
|---|---|---|---|
events |
HistoricalEvent[] |
[] |
Required. Array of event objects to display. |
categories |
TimelineCategory[] |
[] |
Definitions for event categories (label, color). |
initialRange |
TimelineRange |
1900-2000 |
Initial start and end dates for the view. |
themeColor |
string |
#A58EFF |
Primary accent color. |
isDarkMode |
boolean |
true |
Toggle between dark and light themes. |
theme |
TimelineTheme |
{} |
Custom theme object for deep color overrides. |
density |
number |
1 |
Vertical spacing multiplier for events. |
showControls |
object |
all: true |
Toggle UI elements: search, legend, scrubber, eventsCount. |
labels |
TimelineLabels |
default |
Custom strings for UI text and placeholders. |
dateFormatter |
(date) => string |
internal |
Custom function to format dates in the UI. |
onEventClick |
(event) => void |
internal |
Callback when an event card is clicked. |
onRangeChange |
(range) => void |
undefined |
Callback when the timeline range is updated. |
zoomConstraints |
ZoomConstraints |
undefined |
Set minRange and maxRange (in ms). |
stepSize |
number |
undefined |
Snapping interval for the timeline (in ms). |
renderCustomIcon |
(event) => ReactNode |
undefined |
Custom icon renderer for event cards. |
renderCustomDetail |
(event, close) => ReactNode |
undefined |
Custom renderer for the event detail modal. |
className |
string |
"" |
Additional CSS class for the container. |
interface HistoricalEvent {
id: string;
time: Date;
date: string; // Display string (e.g., "July 1969")
title: string;
description: string;
category: string;
imageUrl?: string; // Background image for card/modal
icon?: string; // Emoji or character icon
}interface TimelineCategory {
id: string;
label: string;
color: string; // Hex, RGB, etc.
}PanoramaTimeline uses CSS variables for all its colors. You can override them in your CSS:
:root {
--pt-primary: #a58eff;
--pt-bg: #020617;
--pt-text: #f8fafc;
--pt-text-muted: #94a3b8;
--pt-border: rgba(30, 41, 59, 0.5);
--pt-surface: #0f172a;
--pt-surface-elevated: #1e293b;
--pt-grid: #64748b;
--pt-overlay: rgba(2, 6, 23, 0.8);
}The component also supports a .light-mode class which is automatically applied when isDarkMode={false}.
Alternatively, use the theme prop for programmatic styling:
<PanoramaTimeline
theme={{
primary: "#3b82f6",
background: "#ffffff",
text: "#1e293b"
}}
/>If you want to contribute or run the project locally:
- Clone the repo:
git clone https://github.com/rfksna/panorama-timeline.git - Install deps:
npm install - Run dev server:
npm run dev - Build:
npm run build - Lint:
npm run lint
MIT © rfksna