Items

Timeline items are the core data — range events and point-in-time markers.

TempisTimelineItem

PropertyTypeDescription
idstring | numberUnique identifier (required).
startstring | number | DateStart date (required). ISO string, timestamp, or Date.
endstring | number | DateEnd date. Omit for point-in-time items.
labelstringDisplay label.
groupingstringGroup name for row organisation.
categorystringCategory name (must match a defined category).
selectedbooleanWhether the item is initially selected.
progressnumberCompletion progress (0–1). Renders as a fill bar inside range items. Ignored for point-in-time items.
styleTempisTimelineItemStylePer-item style overrides.
Item IDs must be unique across the entire timeline. Duplicate IDs will cause unexpected behaviour with selection, focus, and dependency rendering.
Dates can be ISO strings ('2026-01-15'), Unix timestamps in milliseconds, or Date objects.

Range Items vs Point-in-Time

Items with both start and end render as horizontal bars. Items with only start render as point-in-time markers with a downward triangle.

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

const timeline = new TempisTimeline('#canvas', {
  responsive: true,
  items: [
    { id: 1, label: 'Item 1',  start: '2026-01-05', end: '2026-01-19', grouping: 'Range Items' },
    { id: 2, label: 'Item 2',  start: '2026-01-20', end: '2026-02-02', grouping: 'Range Items' },
    { id: 3, label: 'Item 3',  start: '2026-01-08', end: '2026-01-16', grouping: 'Range Items' },
    { id: 4, label: 'Event 1', start: '2026-01-05', grouping: 'Point-in-Time' },
    { id: 5, label: 'Event 2', start: '2026-01-19', grouping: 'Point-in-Time' },
    { id: 6, label: 'Event 3', start: '2026-02-02', grouping: 'Point-in-Time' },
    { id: 7, label: 'Event 4', start: '2026-02-10', grouping: 'Point-in-Time' },
  ],
  range: { start: '2026-01-01', end: '2026-02-15', position: 'bottom' }
});

Methods

setItems(items)

Replaces all items and redraws the timeline.

timeline.setItems([
  { id: 1, label: 'Item 1', start: '2026-02-01', end: '2026-02-10' }
]);

getItems()

Returns the current item definitions.

const items = timeline.getItems();

Per-Item Styles

Override the default appearance on individual items.

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

const timeline = new TempisTimeline('#canvas', {
  responsive: true,
  items: [
    { id: 1, label: 'Item 1 (Default)', start: '2026-01-05', end: '2026-01-15' },
    { id: 2, label: 'Item 2 (Dashed)', start: '2026-01-10', end: '2026-01-22',
      style: { backgroundColor: '#6366f1', borderColor: '#818cf8', borderThickness: 2, borderStyle: 'dashed' } },
    { id: 3, label: 'Item 3 (Rounded)', start: '2026-01-18', end: '2026-01-28',
      style: { backgroundColor: '#7c3aed', fontColor: '#fff', borderRadius: 12 } },
    { id: 4, label: 'Item 4 (Dotted)', start: '2026-01-08', end: '2026-01-20',
      style: { backgroundColor: '#059669', borderColor: '#34d399', borderThickness: 2, borderStyle: 'dotted' } },
    { id: 5, label: 'Item 5 (Styled)', start: '2026-01-14', end: '2026-01-19',
      style: { backgroundColor: '#e11d48', borderColor: '#9f1239', borderThickness: 2, borderStyle: 'dashed', borderRadius: 8 } },
    { id: 6, label: 'Item 6 (Long Dash)', start: '2026-01-22', end: '2026-01-30',
      style: { backgroundColor: '#0ea5e9', borderColor: '#38bdf8', borderThickness: 2, borderStyle: 'long-dash' } },
  ],
  range: { start: '2026-01-01', end: '2026-02-01', position: 'bottom' }
});

Progress Indicator

Range items can display a progress fill bar by setting the progress property to a value between 0 and 1. The fill renders as a lighter overlay from the left edge, clipped to the item's border radius. The progress property is ignored for point-in-time items. Values are clamped to the 0–1 range.

const timeline = new TempisTimeline('#canvas', {
  responsive: true,
  items: [
    { id: 1, label: 'Item 1 (100%)', start: '2026-02-01', end: '2026-02-14', progress: 1.0 },
    { id: 2, label: 'Item 2 (70%)',  start: '2026-02-05', end: '2026-02-20', progress: 0.7 },
    { id: 3, label: 'Item 3 (40%)',  start: '2026-02-10', end: '2026-02-25', progress: 0.4 },
    { id: 4, label: 'Item 4 (0%)',   start: '2026-02-15', end: '2026-02-28', progress: 0 },
    { id: 5, label: 'Event 1',       start: '2026-02-12' },
  ],
  range: { start: '2026-01-28', end: '2026-03-05', position: 'bottom' }
});
Progress is rendered as a semi-transparent white overlay (rgba(255, 255, 255, 0.2)) so it works with any background colour. In RTL mode, the fill starts from the right edge.