Grouping

Organise items into labelled rows with optional custom sort order and collapse.

TempisTimelineGroupingOptions

PropertyTypeDefaultDescription
sort(a: string, b: string) => number—Comparator function for group ordering. Receives two group names. If omitted, groups appear in the order they are first encountered in the items array.
collapsiblebooleanfalseWhether groups can be collapsed by clicking their header. A chevron indicator appears next to each group label.

Items are assigned to groups via the grouping property on each item. Items sharing the same grouping value are rendered in the same row section.

Items without a grouping property are placed in a default unnamed group. If all items have groupings, no unnamed group appears.

Collapsible Groups

When collapsible is true, each group header displays a chevron indicator. Click the header to collapse or expand the group. Collapsed groups hide their items and take up minimal vertical space.

Methods

MethodDescription
setGroupCollapsed(group, collapsed?)Set or toggle the collapsed state of a group. Pass true to collapse, false to expand, or omit the second argument to toggle.
isGroupCollapsed(group)Returns whether a group is currently collapsed.

Callback

onGroupToggle(group: string, collapsed: boolean) fires when a user clicks a group header to collapse or expand it. It does not fire for programmatic calls to setGroupCollapsed().

const timeline = new TempisTimeline('#canvas', {
  responsive: true,
  grouping: { collapsible: true },
  items: [
    { id: 1, label: 'Item 1', start: '2026-01-05', end: '2026-01-15', grouping: 'Group 1' },
    { id: 2, label: 'Item 2', start: '2026-01-08', end: '2026-01-20', grouping: 'Group 2' },
  ],
  range: { start: '2026-01-01', end: '2026-02-01', position: 'bottom' },
  onGroupToggle(group, collapsed) {
    console.log(group, collapsed ? 'collapsed' : 'expanded');
  }
});

// Programmatic control
timeline.setGroupCollapsed('Group 1', true);   // collapse
timeline.setGroupCollapsed('Group 1', false);  // expand
timeline.setGroupCollapsed('Group 1');          // toggle
timeline.isGroupCollapsed('Group 1');           // check state

Example

const timeline = new TempisTimeline('#canvas', {
  responsive: true,
  grouping: {
    collapsible: true,
    sort(a, b) {
      return a.localeCompare(b);
    }
  },
  items: [
    { id: 1, label: 'Item 1', start: '2026-01-05', end: '2026-01-15', grouping: 'Group 3' },
    { id: 2, label: 'Item 2', start: '2026-01-08', end: '2026-01-20', grouping: 'Group 1' },
    { id: 3, label: 'Item 3', start: '2026-01-12', end: '2026-01-25', grouping: 'Group 2' },
    { id: 4, label: 'Item 4', start: '2026-01-18', end: '2026-01-28', grouping: 'Group 1' },
    { id: 5, label: 'Item 5', start: '2026-01-10', end: '2026-01-22', grouping: 'Group 3' },
    { id: 6, label: 'Item 6', start: '2026-01-20', end: '2026-01-30', grouping: 'Group 2' },
  ],
  range: { start: '2026-01-01', end: '2026-02-01', position: 'bottom' }
});