Tooltips

Show contextual information when hovering over timeline items.

Hover over items to see custom tooltips.

Overview

Tooltips appear when the user hovers over a timeline item. By default, they show the item label and date range. You can fully customise the content using a template function, control when they appear, adjust their positioning, and add a delay.

TempisTimelineTooltipOptions

Property	Type	Default	Description
`enabled`	`boolean`	`true`	Enable or disable tooltips globally. Set to `false` to suppress all tooltips.
`delay`	`number`	`0`	Delay in milliseconds before the tooltip appears after hovering an item. Useful to avoid flickering when the user moves quickly across items.
`dateFormat`	`string`	`"D MMMM HH:mm:ss"`	The date format pattern used in the default tooltip. Uses the same tokens as the date adapter (see Date Adapters).
`overflowBehavior`	`"none" \| "canvas" \| "viewport"`	`"none"`	Controls how the tooltip repositions when it would overflow an edge.
`template`	`(id: string \| number) => HTMLElement \| string \| null`	—	Custom template function for full control over tooltip content.
`shouldShow`	`(id: string \| number) => boolean`	—	Predicate that controls whether a tooltip appears for a specific item.

Default Tooltip

When no template is provided, the timeline renders a default tooltip showing:

The item label
The start date (formatted using dateFormat)
The end date (for range items)

You can customise the date format without writing a full template:

tooltip: {
  dateFormat: 'D MMM YYYY'  // Shows "5 Jan 2026" instead of "5 January 14:00:00"
}

Overflow Behaviour

Tooltip positioning is relative to the cursor. When a tooltip would extend beyond an edge, the overflowBehavior setting controls what happens:

"none" — the tooltip renders at the cursor position and may be clipped by the canvas or viewport. Use this when you want full control over positioning via CSS.
"canvas" — the tooltip flips horizontally or vertically to stay within the canvas element bounds. Good for timelines embedded in scrollable containers.
"viewport" — the tooltip flips to stay within the browser viewport. Best for most use cases — ensures the tooltip is always fully visible.

tooltip: {
  overflowBehavior: 'viewport'
}

Custom Template

The template function gives you full control over tooltip content. It receives the item ID and should return one of:

An HTML string — injected as innerHTML into the tooltip container.
An HTMLElement — appended directly as the tooltip content.
null — falls back to the default tooltip for that item.

Returning a HTML String

Hover to see the HTML string tooltip with duration.

const timeline = new TempisTimeline('#canvas', {
  items: [
    { id: 1, label: 'Design Sprint', start: '2026-04-01', end: '2026-04-14' },
    { id: 2, label: 'Development', start: '2026-04-10', end: '2026-05-01' },
  ],
  range: { start: '2026-03-25', end: '2026-05-10', position: 'bottom' },
  tooltip: {
    overflowBehavior: 'viewport',
    template(id) {
      const item = timeline.getItems().find(i => i.id === id);
      if (!item) return null;

      const days = item.end
        ? Math.round((new Date(item.end).getTime() - new Date(item.start).getTime()) / 86400000)
        : 0;

      return `
        <div style="padding: 12px 16px; font-family: sans-serif; min-width: 180px;">
          <div style="font-weight: 700; margin-bottom: 6px;">${item.label}</div>
          <div style="font-size: 12px; color: #666;">
            ${days > 0 ? days + ' days' : 'Milestone'}
          </div>
        </div>
      `;
    }
  }
});

Returning a HTMLElement

For complex tooltips or when you want to attach event listeners, return a DOM element:

Hover to see the HTMLElement tooltip.

tooltip: {
  template(id) {
    const item = timeline.getItems().find(i => i.id === id);
    if (!item) return null;

    const el = document.createElement('div');
    el.style.padding = '12px 16px';
    el.style.fontFamily = 'sans-serif';

    const title = document.createElement('strong');
    title.textContent = item.label;
    el.appendChild(title);

    const desc = document.createElement('p');
    desc.style.margin = '4px 0 0';
    desc.style.fontSize = '12px';
    desc.style.color = '#666';
    desc.textContent = `ID: ${item.id}`;
    el.appendChild(desc);

    return el;
  }
}

Conditional Fallback

Return null from the template to use the default tooltip for specific items:

tooltip: {
  template(id) {
    // Only customise tooltips for items with a specific category
    const item = timeline.getItems().find(i => i.id === id);
    if (item?.category === 'milestone') {
      return '<div style="padding: 8px;">🎯 Milestone reached</div>';
    }
    return null; // Default tooltip for everything else
  }
}

shouldShow Predicate

Use shouldShow to conditionally suppress tooltips for specific items without disabling them globally. The function receives the item ID and should return true to show the tooltip or false to suppress it.

tooltip: {
  shouldShow(id) {
    // Only show tooltips for range items (not milestones)
    const item = timeline.getItems().find(i => i.id === id);
    return !!item?.end;
  }
}

When shouldShow returns false, no tooltip is rendered at all — the template function is not called.

Styling

The tooltip container is a plain <div> positioned absolutely near the cursor. It has no default styling beyond positioning — your template controls the appearance entirely. For rich card-style tooltips, include padding, background, border-radius, and box-shadow in your template HTML.

Hover over items to see the styled card tooltip.

tooltip: {
  overflowBehavior: 'viewport',
  template(id) {
    const item = timeline.getItems().find(i => i.id === id);
    return `
      <div style="
        padding: 12px 16px;
        background: #fff;
        border-radius: 8px;
        box-shadow: 0 4px 12px rgba(0,0,0,0.1);
        font-family: sans-serif;
        font-size: 13px;
      ">
        <strong>${item?.label}</strong>
      </div>
    `;
  }
}