react-canvas-timeline

A high-performance React timeline component built on HTML5 Canvas — designed for rich interactivity, arbitrary time scales, and pixel-perfect rendering at any zoom level.

Why Canvas?

Most timeline and Gantt libraries render rows, bars, and labels as DOM elements. That works fine for small datasets — but it breaks down quickly.

Advantages of the Canvas approach:

Performance at scale — 1,000+ task bars render and scroll smoothly because there is no DOM to reflow or repaint. The canvas is redrawn as a single raster operation.
Unlimited shapes — Bars, pins, speech bubbles, clouds, stars, curly braces, baselines, circles with center text, and more. CSS cannot express these shapes; Canvas can draw anything.
Pixel-precise layout — Every element is positioned and sized to the exact pixel, regardless of browser zoom level, screen DPI, or font scaling.
Consistent cross-browser rendering — Canvas output is identical across all modern browsers. No CSS quirks, no layout engine differences.
Print layout — A dedicated print mode produces clean, paginated output without additional styling effort.
Parallel timelines — Multiple independent timeline instances on the same page work without interference, since each renders to its own canvas.

The common Canvas objection — addressed:

Canvas content is not readable by search engine crawlers or screen readers. react-canvas-timeline solves this by optionally rendering an invisible HTML representation of the timeline data alongside the canvas, making content indexable and accessible without sacrificing rendering performance.

Install

npm install --save react-canvas-timeline

Quick Start

import { ReactCanvasTimeline, Resource, Task, LCal } from 'react-canvas-timeline';

const resources = [
  new Resource(0, 'Alice', 'Developer', false),
  new Resource(1, 'Bob',   'Designer',  false),
];

const now = new LCal().initNow();

const tasks = [
  new Task(0, now.clone(), now.clone().addDay(5),  0, 'Task A', '', null),
  new Task(1, now.clone().addDay(3), now.clone().addDay(10), 1, 'Task B', '', null),
];

export default function App() {
  return (
    <ReactCanvasTimeline
      resources={resources}
      tasks={tasks}
      width={900}
      height={400}
    />
  );
}

Run the Storybook for full working examples:

npm run storybook

LCal — Cosmic Time Range

react-canvas-timeline uses its own calendar system, LCal, instead of JavaScript's Date. This allows representing any point in time from the Big Bang to the far future, internally stored as a Julian day number with minute resolution.

Precision levels

Every LCal value carries a precision that describes how accurately the point in time is known. This is used both for display (labels adapt to the granularity) and for rendering (bars representing geological epochs look different from bars representing a single day).

Level	Granularity
0	1 Gigayear
1	100 Megayears
2	10 Megayears
3	1 Megayear
4	100 Kiloyears
5	10 Kiloyears
6	1 Kiloyear
7	100 years
8	10 years
9	1 year
10	1 month
11	1 day
12	1 hour
13	1 minute

A single timeline can mix tasks at different precision levels — a geological epoch alongside a modern calendar appointment.

Features

Core

Story	Feature
`01`	1,000-bar stress test — 100 resources, 1,000 tasks rendered and scrolled without frame drops
`02`	Hierarchy — Resources and tasks support parent–child nesting with collapse/expand
`32`	Zoom & fit — Programmatic zoom-to-fit-all and zoom-to-selection

Visual Customization

Story	Feature
`12`	Bar size — Configurable bar height per timeline
`13`	Bar groups — Group bars by color and shape within a resource row
`16`	Shapes & sizes — Full shape catalog: `RECT`, `PIN_INTERVAL`, `SMALL_PIN_INTERVAL`, `CLOUD`, `CURLYBRACE`, `STAR`, `CIRCLE`, `SPEECHBUBBLE`, `CIRCLE_MIDDLETEXT`, `BASELINE`, `TRANSPARENTBACK` with transparency and font templates
`20`	Speech bubbles — Callout shapes with configurable direction
`21`	Cloud shapes — Organic cloud-style task bars
`03`	Icons — Per-resource and per-task icon images
`18`	Short labels — Compact label mode for PIN_INTERVAL and SMALL_PIN_INTERVAL
`29`	Multiline labels — Text wraps across multiple lines; bar expands vertically to fit
`35`	Transparent shapes — Background-only shapes without fill
`37`	Baseline — Render only a baseline marker with no bar body
`34`	Circle with center text — Circle shape displaying text in the center

Theming

Story	Feature
`31`	Bright / dark background — Toggle between light and dark themes at runtime
`09`	Wait overlay styling — Custom loading overlay with full style control

Interactivity & Events

Story	Feature
`05`	Event callbacks — `onClick`, `onPress`, `onLongPress`, `onMouseMove`, `onMousePan` with full position and task context
`06`	Drag & drop — Drag tasks to new times or resources; `onDrop` callback with position data
`07`	Highlight & scroll-to — Programmatically highlight a task and scroll it into view
`08`	Measure intervals — Draggable interval sliders for measuring durations on the canvas
`24`	Dynamic shape changes — Change task shapes at runtime without full re-render

Layout & Controls

Story	Feature
`19`	Resource headers — Three modes: `default` (200 px sidebar), `inline` (40 px compact row), or no header
`10`	Additional controls — Inject custom JSX into the vertical and horizontal slider areas
`27`	No sliders — Render the timeline without any navigation sliders
`11`	Print layout — Collapse indicators hidden; output optimized for printing
`14`	Responsive resize — Adapt width and height dynamically as the container resizes
`15`	Parallel timelines — Multiple independent timeline instances on the same page
`23`	Config overrides — Fine-grained control over colors, fonts, spacing, and behavior via the `config` prop

Advanced

Story	Feature
`39`	Connections — Draw labeled arrows between tasks across resources
`38`	Resource decorations — Per-resource header colors and background decorations
`04`	Task backgrounds — Custom painter for the area behind task bars (e.g. agreed-time shading)
`25`	Embedded diagrams — Paint arbitrary chart data (line, bar, etc.) directly onto the canvas within a resource row
`26`	Invisible HTML — Render an invisible HTML layer for SEO indexing and screen-reader accessibility
`33`	Offscreen image rendering — Toggle offscreen canvas pre-rendering for complex scenes
`30`	Position & bar group features — Combined demo of positioning and grouping capabilities
`40`	Error handling — Graceful handling of invalid or missing task data

Precision & Time Scale

Story	Feature
`17`	All precision levels — Visual demonstration of all 14 precision levels on one timeline
`28`	Precision with images & labels — Precision levels 7–13 combined with icons, labels, and multiple shapes

Internationalization

Story	Feature
`36`	Language switching — Switch between German, English, and Ukrainian at runtime via `languageCode` prop
`41`	Current date indicator callbacks — Custom formatting for the date label shown at the cursor position

Props Reference