vis-timeline-canvas

A high-performance, canvas-based fork of vis-timeline. It keeps the familiar data model (plain arrays or vis-data DataSets of items and groups) but replaces the one-DOM-node-per-item renderer with a single <canvas>, so it stays fast into the tens of thousands of items.

• Drop-in-ish data model — items/groups look like vis-timeline's.
• Canvas rendering — viewport culling, cached text widths and group heights.
• Extras not in stock vis-timeline — minimap, follow-now, time probe, uniform-color + accent strips, error stripes, block-across-subgroups, blocks that gradient/cover, per-instance theming, leading item icons, a left scrollbar, and desktop keyboard navigation.

Migrating an existing integration? See transition.html. Go/no-go analysis: risks.html. Deferred perf work: optimizations.html.

Install

An ESM package, installable from source — a git URL, a local path, or a packed tarball:

# from the git repo
npm install git+ssh://git@gitlab.com:willjessop12/canvas-timeline.git

# or from a local checkout / packed tarball
npm install /path/to/canvas-timeline
npm pack   # -> vis-timeline-canvas-x.y.z.tgz, then `npm install ./that.tgz`

The package depends on vis-timeline and vis-data so it stays consistent and interoperable with an existing vis-timeline / vis-data integration. It does not import vis-timeline's source (renderer) — it only duck-types DataSets — so it stays light; vis-timeline is declared for ecosystem consistency and the parallel-run migration path (see transition.html).

For convenience the package re-exports the data containers, so you can import the timeline and its DataSet from one place:

import { CanvasTimeline, DataSet } from 'vis-timeline-canvas';

To pull in only the renderer (no vis-data re-export), use the subpath:

import { CanvasTimeline } from 'vis-timeline-canvas/renderer';

Quick start

import { CanvasTimeline, DataSet } from 'vis-timeline-canvas';

const items = new DataSet([
  { id: 1, content: 'Kickoff', start: '2024-01-01T09:00', end: '2024-01-01T11:00', group: 'a' },
  { id: 2, content: 'Review',  start: '2024-01-01T13:00', end: '2024-01-01T15:00', group: 'b' },
]);
const groups = [{ id: 'a', content: 'Team A' }, { id: 'b', content: 'Team B' }];

const timeline = new CanvasTimeline('#timeline', items, {
  groups,
  theme: 'dark',
  height: 500,
});

timeline.on('select', ({ items }) => console.log('selected', items));
timeline.on('itemMove', ({ items }) => items.forEach(m => dataset.update(m)));

Note the two API differences from vis-timeline highlighted up front:

1. Groups are passed in the options object ({ groups }), not as a third constructor argument.
2. You persist edits. Drag/resize emit itemMove / itemResize; the renderer never writes back to your DataSet on its own.

Options reference

Every option is optional. Defaults are shown in parentheses.

Sizing & layout

Time window & zoom

With no min/max, the bounds are padded ~5% around the data and expanded to a 24-hour minimum span so single-item timelines still open at a sane scale.

Stacking, editing & snapping

Selection & interaction

Appearance

Icons

Overlays

Item fields

{
  id, start,            // required
  end,                  // omit => a "box" item (point-in-time)
  content,              // plain text label (HTML is NOT parsed)
  group,                // group id
  type,                 // 'range' | 'box' | 'block'
  title,                // plain-text tooltip
  // colors (preferred over a CSS `style` string)
  backgroundColor, borderColor, color,
  // canvas extras
  accentColor,          // bottom strip color in uniform mode
  pattern,              // true | 'stripes' — diagonal stripe overlay (errors)
  patternColor,
  noText,               // hide the label; renders a compact marker
  icon, icons,          // leading icon name(s)
  // block-only (type:'block')
  layer,                // 'back' (default) | 'front' (covers items)
  onTop,                // alias for layer:'front'
  opacity,              // override block fill alpha
  gradient,             // true (auto) | ['#a','#b'] color stops
  gradientDirection,    // 'vertical' (default) | 'horizontal'
}

Group fields

{
  id, content,
  order,                // sort key
  nestedGroups,         // [childId, ...] to nest groups
  showNested,           // start expanded (default true)
  visible,              // hide the group
  backgroundColor, color,
  accentColor,          // highlight tint
}

Events

Subscribe with timeline.on(name, cb) / unsubscribe with off.

Methods

setItems · setGroups · getGroups · getItemCount · fit · setWindow · getWindow · moveTo · zoomIn · zoomOut · toggleFullscreen · isFullscreen · setSelection · getSelection · toggleGroupCollapse · setGroupHighlight · clearGroupHighlights · setFollowNow · isFollowingNow · setTheme · on · off · redraw · destroy. See src/canvas-timeline.d.ts for full signatures.

Keyboard (when keyboard is on)

Click the timeline to focus it, then:

• ← / → — move the selection to the previous/next item within the same group (stays on one row band; pans when nothing is selected).
• ↑ / ↓ — move to the nearest-in-time item in the adjacent group.
• Shift + ← / → — nudge the selected item(s) in time.
• + / − — zoom in/out. F — fit. Home / End — first/last item.
• Esc — clear selection. Enter — activate (emits doubleClick).

How this fork diverges from vis-timeline

These are the behaviors most likely to surprise you when migrating. Worked examples are in EXAMPLES.html.

• No HTML templates. template/groupTemplate are not supported — the canvas draws plain text + shapes. Convert template logic into data-driven fields (backgroundColor, pattern, icons, …).
• className / CSS classes do nothing. Style via data fields instead.
• Groups go in options, not the third constructor argument.
• You persist edits via itemMove/itemResize.
• Item types: box, range, and the new block. point and background are not implemented.
• Plain-text tooltips only (the title field). For rich content, render your own overlay on doubleClick/contextmenu.

See transition.html for the full migration plan and a parallel-run harness.

Project layout

The renderer is one class spread across focused modules. The big method groups are defined as "mixin" classes and copied onto CanvasTimeline.prototype at load (see src/mixin.js), so they share one this while living in separate, readable files.

index.js               package entry: re-exports CanvasTimeline + DataSet/DataView
index.d.ts             package types
src/
  canvas-timeline.js   core: constructor, options, public API, setup, data
  mixin.js             applyMixins(target, ...sources)
  timeline/
    layout.js          viewport/time-bounds math, stacking, snapping
    rendering.js       the canvas draw path (grid, items, blocks, axis, minimap)
    interaction.js     pointer + keyboard input, drag/resize, hit-testing
  theme.js             light/dark presets + buildTheme()
  colors.js            lighten / darken / withAlpha
  canvas-draw.js       roundRect / truncateText
  time-format.js       axis + probe label formatting
  canvas-timeline.d.ts TypeScript declarations

Run the tests with npm test (layout/unit assertions + a headless render smoke test).

← Back to demos & docs · Examples & recipes →