Selection

Let users select one or more timeline items.

Selection Modes

Mode	Description
`"none"`	Items cannot be selected (default).
`"single"`	One item at a time. Clicking a new item deselects the previous one.
`"multi"`	Multiple items can be toggled independently.

Methods

setSelection(ids)

Programmatically selects items by their identifiers. Deselects all items not in the provided array.

timeline.setSelection([1, 3]);

getSelection()

Returns the identifiers of the currently selected items.

const selected = timeline.getSelection(); // [1, 3]

clearSelection()

Deselects all items and redraws.

timeline.clearSelection();

Controlled vs Uncontrolled

Selection behaviour depends on whether onSelectionChange is provided:

Uncontrolled (no onSelectionChange) — the timeline manages selection state internally. Clicking an item selects it and redraws automatically.
Controlled (with onSelectionChange) — the timeline fires the callback but does not update selection state. You must call setSelection() yourself to apply the changes. This gives you full control over selection logic.

If you provide onSelectionChange, you are responsible for calling setSelection() to update the visual state. Without it, clicks will fire the callback but items won't appear selected.

Callback

onSelectionChange

Fires whenever the selection changes, whether by user interaction or programmatic update. Receives an array of SelectionChangeEvent objects describing which items were selected or deselected.

onSelectionChange(changes: SelectionChangeEvent[]): void

Example — Uncontrolled

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

// No onSelectionChange — selection is managed automatically
const timeline = new TempisTimeline('#canvas', {
  responsive: true,
  selection: 'multi',
  items: [
    { id: 1, label: 'Item 1', start: '2026-03-01', end: '2026-03-10', grouping: 'Group 1' },
    { id: 2, label: 'Item 2', start: '2026-03-05', end: '2026-03-15', grouping: 'Group 1' },
  ],
  range: { start: '2026-02-25', end: '2026-04-01', position: 'bottom' }
});

Example — Controlled

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

const timeline = new TempisTimeline('#canvas', {
  responsive: true,
  selection: 'multi',
  items: [
    { id: 1, label: 'Item 1', start: '2026-03-01', end: '2026-03-10', grouping: 'Group 1' },
    { id: 2, label: 'Item 2', start: '2026-03-05', end: '2026-03-15', grouping: 'Group 1' },
  ],
  range: { start: '2026-02-25', end: '2026-04-01', position: 'bottom' },
  onSelectionChange(changes) {
    // Apply the selection changes manually
    const current = timeline.getSelection();
    changes.forEach(change => {
      if (change.selected) {
        current.push(change.id);
      } else {
        const idx = current.indexOf(change.id);
        if (idx !== -1) current.splice(idx, 1);
      }
    });
    timeline.setSelection(current);
  }
});