https://github.com/thbst16/react-simile-timeline
Modern React timeline component based on MIT's Simile Timeline. TypeScript, WCAG 2.1 AA accessible, touch-enabled, 60fps performance. Compatible with original Simile JSON format.
https://github.com/thbst16/react-simile-timeline
accessibility data-visualization events-timeline react-component responsive timeline-component typescript
Last synced: 3 months ago
JSON representation
Modern React timeline component based on MIT's Simile Timeline. TypeScript, WCAG 2.1 AA accessible, touch-enabled, 60fps performance. Compatible with original Simile JSON format.
- Host: GitHub
- URL: https://github.com/thbst16/react-simile-timeline
- Owner: thbst16
- License: mit
- Created: 2025-11-08T15:53:48.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-12-19T01:42:32.000Z (4 months ago)
- Last Synced: 2025-12-21T22:07:18.025Z (4 months ago)
- Topics: accessibility, data-visualization, events-timeline, react-component, responsive, timeline-component, typescript
- Language: TypeScript
- Homepage: https://react-simile-timeline-demo.vercel.app/
- Size: 1.17 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# React Simile Timeline
[](https://github.com/thbst16/react-simile-timeline/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/react-simile-timeline)
[](https://www.npmjs.com/package/react-simile-timeline)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
A modern React implementation of the [MIT SIMILE Timeline](https://www.simile-widgets.org/timeline/) visualization component. Build beautiful, interactive timelines with ease.
Live Demo •
Installation •
Quick Start •
API •
GitHub
---
## Why React Simile Timeline?
| Feature | Description |
|---------|-------------|
| **100% Simile Compatible** | Drop-in replacement for existing Simile Timeline JSON data |
| **High Performance** | 60+ FPS smooth scrolling with optimized rendering |
| **Modern Stack** | Built with React 18/19, TypeScript, and hooks |
| **Multi-Band** | Two-band, three-band, or custom configurations |
| **Fully Themeable** | Classic, dark, and custom themes via CSS variables |
| **Accessible** | ARIA labels, keyboard navigation, screen reader support |
| **Lightweight** | ~12KB gzipped, zero runtime dependencies |
---
## Installation
```bash
npm install react-simile-timeline
```
```bash
yarn add react-simile-timeline
```
```bash
pnpm add react-simile-timeline
```
---
## Quick Start
```tsx
import { Timeline } from 'react-simile-timeline';
import 'react-simile-timeline/style.css';
function App() {
const data = {
dateTimeFormat: 'iso8601',
events: [
{ start: '2024-01-15', title: 'Project Started', color: '#4a90d9' },
{ start: '2024-03-01', end: '2024-06-30', title: 'Development', isDuration: true, color: '#6b8e5f' },
{ start: '2024-07-01', title: 'Launch Day', color: '#c41e3a' },
],
};
return ;
}
```
---
## Examples
### Load Data from URL
```tsx
console.log(event)}
/>
```
### Hot Zones (Highlighted Periods)
```tsx
```
### Multi-Band Timeline
```tsx
```
### Dark Theme
```tsx
```
### Custom Theme
```tsx
```
---
## API Reference
### Timeline Props
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `TimelineData` | - | Inline timeline data |
| `dataUrl` | `string` | - | URL to fetch timeline JSON |
| `dataUrls` | `string[]` | - | Multiple URLs to fetch and merge |
| `bands` | `BandConfig[]` | Auto | Band configuration array |
| `hotZones` | `HotZone[]` | `[]` | Highlighted time periods |
| `theme` | `'classic' \| 'dark' \| Theme` | `'classic'` | Theme configuration |
| `centerDate` | `string \| Date` | Median | Initial center date |
| `width` | `string \| number` | `'100%'` | Container width |
| `height` | `string \| number` | `400` | Container height |
| `onEventClick` | `(event) => void` | - | Event click callback |
| `onEventHover` | `(event) => void` | - | Event hover callback |
| `branding` | `boolean \| BrandingConfig` | - | Show watermark |
| `className` | `string` | - | Container CSS class |
### Event Properties
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `start` | `string` | Yes | Start date (ISO 8601) |
| `title` | `string` | Yes | Display title |
| `end` | `string` | No | End date for duration events |
| `description` | `string` | No | Shown in popup |
| `isDuration` | `boolean` | No | Force duration rendering |
| `color` | `string` | No | Background color |
| `textColor` | `string` | No | Label text color |
| `icon` | `string` | No | URL to custom icon |
| `image` | `string` | No | URL to event image |
| `link` | `string` | No | URL for "more info" |
### TypeScript Types
```typescript
interface TimelineData {
dateTimeFormat?: 'iso8601' | 'Gregorian' | string;
events: TimelineEvent[];
}
interface BandConfig {
id?: string;
height?: string;
timeUnit?: 'day' | 'week' | 'month' | 'year' | 'decade' | 'century';
intervalPixels?: number;
overview?: boolean;
syncWith?: string;
}
interface HotZone {
start: string;
end: string;
color?: string;
annotation?: string;
}
interface Theme {
name: string;
backgroundColor?: string;
eventColor?: string;
eventTextColor?: string;
scaleColor?: string;
gridColor?: string;
}
```
### Keyboard Navigation
| Key | Action |
|-----|--------|
| `←` / `→` | Pan left/right |
| `+` / `=` | Zoom in |
| `-` | Zoom out |
| `Escape` | Close popup |
---
## Simile JSON Compatibility
This library is 100% compatible with the original Simile Timeline JSON format:
```json
{
"dateTimeFormat": "iso8601",
"events": [
{
"start": "1963-11-22",
"title": "JFK Assassination",
"description": "President Kennedy assassinated in Dallas, Texas.",
"color": "#c41e3a"
}
]
}
```
**Supported date formats:**
- ISO 8601: `2023-01-15`, `2023-01-15T10:30:00`
- Legacy: `Jan 15 2023`, `January 15, 2023`
- Year only: `2023`, `-500` (BCE)
---
## Browser Support
| Browser | Support |
|---------|---------|
| Chrome | Latest |
| Firefox | Latest |
| Safari | Latest |
| Edge | Latest |
---
## Contributing
Contributions are welcome! Please read our [Contributing Guide](https://github.com/thbst16/react-simile-timeline/blob/main/CONTRIBUTING.md) for details.
---
## License
MIT License - see [LICENSE](https://github.com/thbst16/react-simile-timeline/blob/main/LICENSE) for details.
---
## Links
- [Live Demo](https://react-simile-timeline.vercel.app/)
- [GitHub Repository](https://github.com/thbst16/react-simile-timeline)
- [Issue Tracker](https://github.com/thbst16/react-simile-timeline/issues)
- [Changelog](https://github.com/thbst16/react-simile-timeline/blob/main/CHANGELOG.md)
---
Made with React • TypeScript • MIT SIMILE Timeline