Install

npm install @tempis/timeline

Or via CDN:

<script src="https://unpkg.com/@tempis/timeline/dist/tempis_timeline.min.js"></script>

Quick Start

import { TempisTimeline } from '@tempis/timeline';

const timeline = new TempisTimeline('#canvas', {
  responsive: true,
  items: [
    { id: 1, label: 'Design',  start: '2026-01-05', end: '2026-01-15', grouping: 'Frontend' },
    { id: 2, label: 'Build',   start: '2026-01-12', end: '2026-01-28', grouping: 'Frontend' },
    { id: 3, label: 'Launch',  start: '2026-01-30', grouping: 'Frontend' },
    { id: 4, label: 'API',     start: '2026-01-08', end: '2026-01-25', grouping: 'Backend' },
  ],
  range: { start: '2026-01-01', end: '2026-02-01', position: 'bottom' }
});

Script tag usage:

<script>
  new tempis_timeline.TempisTimeline('#canvas', { /* ... */ });
</script>

Features

• Canvas rendering — no DOM nodes per item
• Range and point-in-time items with automatic stacking
• Categories with interactive legend (filter on click, highlight on hover)
• Item groupings with custom sort and collapsible headers
• Timeline bands (range markers, point markers, lines)
• Item dependencies with automatic connector routing and RTL support
• Per-item style overrides (colors, borders, dash patterns, radius, padding)
• Progress indicator on range items
• Tooltips with custom templates, delay, and overflow handling
• Selection modes: none, single, multi
• Animated focus with configurable easing
• Zoom, pan, touch pinch, keyboard navigation
• Vertical fill modes: content, fill-canvas, grow-canvas
• Stack modes: compact, stable
• RTL layout
• Responsive resize
• Image export (PNG, JPEG, WebP) with DPR and background color
• Pluggable date adapters (native, Luxon, Day.js, etc.)
• Global color palette API
• Configurable scrollbar styling
• Minimap overview bar with click/drag navigation
• Accessibility: keyboard navigation, ARIA attributes, reduced motion support
• 100% TypeScript with full declarations

API

Constructor

new TempisTimeline(context: string | HTMLCanvasElement, options: TempisTimelineOptions)

Methods

| Method | Description | |--------|-------------| | setItems(items) | Replace all items and redraw | | getItems() | Get current item definitions | | setCategories(categories) | Replace all categories and redraw | | getCategories() | Get current category definitions | | setBands(bands) | Replace all bands and redraw | | setDependencies(deps) | Replace all dependencies and redraw | | setGroupCollapsed(group, collapsed?) | Set or toggle a group's collapsed state | | isGroupCollapsed(group) | Check if a group is collapsed | | focus(options?) | Navigate to an item, date, or range with animation | | getRange() | Current visible range as { start, end } | | setSelection(ids) | Programmatically select items by ID | | getSelection() | Array of selected item IDs | | clearSelection() | Deselect all items | | toImage(options?) | Export as image Blob | | redraw() | Force a redraw | | destroy() | Clean up all listeners and resources |

Callbacks

| Callback | Signature | |----------|-----------| | onItemClick | (id: string \| number) => void | | onItemDoubleClick | (id: string \| number) => void | | onItemContextClick | (id: string \| number, position: { x: number; y: number }) => void | | onItemHover | (id: string \| number \| null) => void | | onSelectionChange | (changes: SelectionChangeEvent[]) => void | | onRangeChange | (start: Date, end: Date) => void | | onGroupToggle | (group: string, collapsed: boolean) => void |

Browser Support

Chrome, Edge, Firefox, Safari, Opera (latest versions).

Documentation

Full API documentation and guides are available at tempis.dev/api/core/getting-started.

Browse interactive examples at tempis.dev/examples.

Licence

Free for personal projects, education, and evaluation. A paid licence is required for commercial use where revenue is generated. See LICENSE for full terms.

Part of the Tempis monorepo.