react-simile-timeline

v1.0.2

Published

5 months ago

A modern React implementation of the MIT SIMILE Timeline visualization component. Create interactive, multi-band timelines with point and duration events, hot zones, themes, and 100% Simile JSON compatibility.

React Simile Timeline

A modern React implementation of the MIT SIMILE Timeline visualization component. Build beautiful, interactive timelines with ease.

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

npm install react-simile-timeline

yarn add react-simile-timeline

pnpm add react-simile-timeline

Quick Start

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 <Timeline data={data} height={400} />;
}

Examples

Load Data from URL

<Timeline
  dataUrl="/api/events.json"
  height={400}
  onEventClick={(event) => console.log(event)}
/>

Hot Zones (Highlighted Periods)

<Timeline
  data={data}
  hotZones={[
    {
      start: '2024-03-01',
      end: '2024-06-30',
      color: 'rgba(107, 142, 95, 0.15)',
      annotation: 'Development Sprint',
    },
  ]}
  height={400}
/>

Multi-Band Timeline

<Timeline
  data={data}
  bands={[
    { id: 'main', height: '70%', timeUnit: 'month', intervalPixels: 100 },
    { id: 'overview', height: '30%', timeUnit: 'year', overview: true, syncWith: 'main' },
  ]}
  height={400}
/>

Dark Theme

<Timeline data={data} theme="dark" height={400} />

Custom Theme

<Timeline
  data={data}
  theme={{
    name: 'ocean',
    backgroundColor: '#0f172a',
    eventColor: '#38bdf8',
    eventTextColor: '#e2e8f0',
    scaleColor: '#94a3b8',
    gridColor: '#334155',
  }}
  height={400}
/>

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

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:

{
  "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 for details.

License

MIT License - see LICENSE for details.