sgpt-timeline

A lightweight, high-performance timeline visualization library for the browser. Render interactive timelines with event groups, events, markers, and connections on HTML5 Canvas.

Features

• Canvas-based rendering with high-DPI support
• Event Groups — labeled rows with optional grouping and custom styles
• Events — points in time on event group rows, with drag support
• Markers — vertical time indicators, draggable
• Connections — lines between events with certainty levels
• Interactions — pan, zoom, click, hover, multi-select, drag
• TypeScript — full type definitions included
• Lightweight — zero runtime dependencies, ~10 KB gzipped

Install

npm install sgpt-timeline

Quick Start

<div id="timeline" style="width: 100%; height: 400px;"></div>

import { createTimeline } from 'sgpt-timeline';

const tl = createTimeline('timeline');

tl.set({
  eventGroups: {
    server1: { label: 'Server 1', color: '#4fc3f7' },
    server2: { label: 'Server 2', color: '#81c784' },
  },
  events: {
    e1: { eventGroupId: 'server1', time: new Date('2026-01-15T10:00:00'), label: 'Deploy' },
    e2: { eventGroupId: 'server1', time: new Date('2026-01-15T14:30:00'), label: 'Alert' },
    e3: { eventGroupId: 'server2', time: new Date('2026-01-15T12:00:00'), label: 'Restart' },
  },
});

tl.fit();

UMD / Script Tag

<script src="https://unpkg.com/sgpt-timeline"></script>
<script>
  const tl = SgptTimeline.createTimeline('timeline');
</script>

API

createTimeline(target, options?)

Creates a new timeline instance.

• target — string (element ID) or HTMLElement
• options — optional TimelineOptions object

Returns a Timeline instance.

Timeline Methods

Data

| Method | Description | |--------|-------------| | set(data) | Load bulk data (event groups + events), auto-fits the view | | addEventGroup(id, eventGroup) | Add a single event group row | | removeEventGroup(id) | Remove an event group and its events | | updateEventGroup(id, changes) | Partially update an event group | | addEvent(id, event) | Add a single event | | removeEvent(id) | Remove an event and its connections | | updateEvent(id, changes) | Partially update an event | | moveEvent(eventId, newEventGroupId) | Move an event to a different row | | addMarker(marker) | Add a vertical marker | | removeMarker(id) | Remove a marker | | updateMarker(id, changes) | Partially update a marker | | markers() | Get all markers | | markers(markers) | Replace all markers | | addConnection(connection) | Add a connection between events | | removeConnection(id) | Remove a connection | | updateConnection(id, changes) | Partially update a connection | | connections() | Get all connections |

View

| Method | Description | |--------|-------------| | range() | Get current visible range { start, end } | | range(start, end) | Set visible range | | fit() | Auto-fit to show all data | | zoom('in' \| 'out', factor?) | Zoom in/out (default factor: 0.3) | | pan('left' \| 'right', fraction?) | Pan left/right (default fraction: 0.2) |

Selection

| Method | Description | |--------|-------------| | eventSelection() | Get selected event IDs | | eventSelection(ids) | Set selected event IDs | | eventGroupSelection() / eventGroupSelection(ids) | Get/set selected event groups | | markerSelection() / markerSelection(ids) | Get/set selected markers | | connectionSelection() / connectionSelection(ids) | Get/set selected connections | | clearSelection() | Clear all selections |

Options

| Method | Description | |--------|-------------| | options() | Get current resolved options | | options(opts) | Merge partial options |

Accessors

| Method | Description | |--------|-------------| | getEventGroup(id) | Get event group by ID | | getEvent(id) | Get event by ID | | getMarker(id) | Get marker by ID | | getEventGroups() | Get all event groups | | getEvents() | Get all events | | getInRangeEvents() | Get events in the current visible range |

Lifecycle

| Method | Description | |--------|-------------| | destroy() | Remove canvas, detach listeners, clean up |

Events

Listen to timeline events with on(event, callback) and off(event, callback).

tl.on('click', (e) => {
  console.log('Clicked at', e.time);
  if (e.eventId) console.log('Event:', e.eventId);
});

tl.on('selection-change', (e) => {
  console.log('Selected groups:', e.eventGroupIds);
  console.log('Selected events:', e.eventIds);
});

tl.on('event-drag-end', (e) => {
  console.log(`Event ${e.eventId} moved to ${e.time} on ${e.eventGroupId}`);
});

| Event | Payload | Description | |-------|---------|-------------| | click | ClickEvent | Single click on timeline | | double-click | ClickEvent | Double click | | context-menu | ClickEvent | Right click | | hover | HoverEvent | Mouse move / hover | | range | RangeEvent | Visible range changed | | selection-change | SelectionChangeEvent | Any selection changed | | event-group-selection-change | SelectionChangeEvent | Event group selection changed | | event-selection-change | SelectionChangeEvent | Event selection changed | | marker-click | ClickEvent | Marker clicked | | marker-drag-start | MarkerDragEvent | Marker drag started | | marker-drag-move | MarkerDragEvent | Marker being dragged | | marker-drag-end | MarkerDragEvent | Marker drag ended | | event-drag-start | EventDragEvent | Event drag started | | event-drag-move | EventDragEvent | Event being dragged | | event-drag-end | EventDragEvent | Event drag ended |

Options

const tl = createTimeline('timeline', {
  backgroundColor: '#1a1a2e',
  fontFamily: 'Inter, system-ui, sans-serif',
  fontSize: 12,
  scaleHeight: 36,
  bounds: { start: new Date('2026-01-01'), end: new Date('2026-12-31') },
  scales: {
    showAtTop: false,
    showAtBottom: true,
    backgroundColor: 'rgba(0, 0, 0, 0.3)',
    textColor: 'rgba(255, 255, 255, 0.6)',
    gridLineStyle: 'dashed',
    fontSize: 11,            // override scale font size
    fontFamily: 'monospace', // override scale font family
    tickLength: 8,           // tick mark length in px
  },
  eventGroups: {
    rowHeight: 48,
    labelWidth: 170,
    showLines: true,
  },
  events: {
    defaultSize: 6,
    defaultColor: '#4fc3f7',
  },
});

Types

All types are exported for TypeScript consumers:

import type {
  EventGroup, TimelineEvent, Marker, Connection,
  TimelineData, TimelineOptions,
  ClickEvent, HoverEvent, SelectionChangeEvent,
  MarkerDragEvent, EventDragEvent,
} from 'sgpt-timeline';

Browser Support

Any browser that supports HTML5 Canvas and ResizeObserver (all modern browsers).

License

MIT