Custom Tooltips

By default ApexGantt shows a built-in tooltip when hovering a task bar, displaying the task name, start date, end date, duration and progress (a milestone shows its date), plus the predecessor when the task has a dependency. Since 3.20.0 its Duration line matches the Duration column (45 m, 2 wd); before, it showed calendar days. Replace it entirely with a tooltipTemplate function.

Fixed in 3.22.0 (security): the default bar tooltip, the baseline tooltip and the edit dialog title wrote the task name into the page as HTML, so a name such as <img src=x onerror=...> loaded from your data ran script. They now show it as text, and so do the dependency id and the progress value in the default tooltip. Names without <, &, " or ' render exactly as before. Upgrade if task names can come from user input. A custom tooltipTemplate is still yours to escape; see Escaping task data.

tooltipTemplate

tooltipTemplate receives the resolved Task object, the active dateFormat string and (since 3.20.0) a context object, and must return an HTML string. The library renders it as innerHTML inside the tooltip container, so wrap any task data in escapeHtml (exported by apexgantt) as the examples on this page do.

import ApexGantt, { escapeHtml } from 'apexgantt'

const gantt = new ApexGantt(document.getElementById('chart'), {
  series: tasks,
  tooltipTemplate: (task, dateFormat, context) => `
    <div style="padding: 10px 14px; min-width: 200px;">
      <div style="font-weight: 600; margin-bottom: 6px;">${escapeHtml(task.name)}</div>
      <div>Start: <strong>${task.startTime}</strong></div>
      <div>End: <strong>${task.endTime}</strong></div>
      <div>Duration: <strong>${context.durationText}</strong></div>
      <div>Progress: <strong>${task.progress}%</strong></div>
    </div>
  `,
})

The function's type is TooltipTemplate, (task, dateFormat, context?) => string. context is a TooltipTemplateContext (both types are exported since 3.20.0):

FieldTypeDescription
durationTextstringThe task's duration exactly as the Duration column shows it: base units of snapUnit ('45 m', '6 h', '14 d'), or working days ('5 wd') when a calendar is set with day snapping
messagesGanttMessagesSince 3.22.0. The chart's resolved strings (English defaults, the locale pack and locale.messages merged), so a template can reuse translated labels such as messages.tooltipStartLabel
startText / endTextstringSince 3.22.0. The start and end dates as the task list shows them: in locale.displayDateFormat (or the locale pack's display format) when one is set, else in inputDateFormat
tagstringSince 3.22.0. The chart's BCP 47 tag (locale.tag, else the pack's), for formatting numbers and plurals the way the task list does

A two-argument template keeps working. On 3.19 and earlier there is no third argument, so compute the duration from startTime and endTime yourself.

A template that follows the chart's language:

tooltipTemplate: (task, dateFormat, context) => {
  const m = context.messages
  return `
    <div><strong>${m.tooltipTaskLabel}</strong> ${escapeHtml(task.name)}</div>
    <div><strong>${m.tooltipStartLabel}</strong> ${context.startText ?? escapeHtml(task.startTime)}</div>
    <div><strong>${m.tooltipEndLabel}</strong> ${context.endText ?? escapeHtml(task.endTime)}</div>
  `
}

Escaping task data

Whatever the template returns is inserted as HTML. Task names, assignee names and other fields loaded from a server or typed by users can carry markup, so pass them through escapeHtml before they go into the string:

import { escapeHtml } from 'apexgantt'

tooltipTemplate: (task) => `<strong>${escapeHtml(task.name)}</strong>`

escapeHtml replaces &, <, >, " and ', so it is safe inside text and inside quoted attributes. Messages you set in locale.messages or a locale pack are inserted as written and are not escaped for you, so keep untrusted input out of them. The React, Vue and Angular wrappers do not re-export escapeHtml; import it from apexgantt, which they install as a peer dependency.

Task object fields

The task argument is the fully resolved Task object: it extends TaskInput with computed properties:

FieldTypeDescription
idstringUnique task identifier
namestringDisplay name
startTimestringStart date string
endTimestringEnd date string (always present after normalisation)
progressnumberCompletion percentage (0 to 100)
typeTaskType'task' or 'milestone'
showSummaryBarboolean | undefinedtrue on a parent drawn as a summary bar
summaryStart / summaryEndstring | undefinedComputed span of a summary bar
parentIdstring | undefinedParent task ID
wbsstring | undefinedWork Breakdown Structure code (e.g. '1.2.3')
levelnumber | undefinedNesting depth (1 = top-level)
barBackgroundColorstring | undefinedPer-task bar color override
assigneesAssignee[]Assigned people (if set on the task)
baselineBaselineInput | undefinedPlanned start/end if set
leftnumber | undefinedComputed x-offset in the timeline (pixels)
widthnumber | undefinedComputed bar width (pixels)

Styling the tooltip container

Use tooltipBGColor and tooltipBorderColor to style the container that wraps your template's output. The tooltip text uses the chart's font; since 3.20.0 that includes the --apex-gantt-font-family and --apex-gantt-font-size custom properties when they are set on the container (before, tooltips used the fontFamily and fontSize options even then):

const gantt = new ApexGantt(el, {
  series: tasks,
  tooltipBGColor: '#1E293B',
  tooltipBorderColor: '#334155',
  tooltipTemplate: (task) => `
    <div style="padding: 10px 14px; color: #F1F5F9; min-width: 220px;">
      <div style="font-weight: 600; font-size: 14px; margin-bottom: 8px;">${escapeHtml(task.name)}</div>
      <div style="font-size: 12px; display: flex; justify-content: space-between; gap: 16px;">
        <span>Start</span><strong>${task.startTime}</strong>
      </div>
      <div style="font-size: 12px; display: flex; justify-content: space-between; gap: 16px;">
        <span>End</span><strong>${task.endTime}</strong>
      </div>
      <div style="margin-top: 8px; background: #334155; border-radius: 4px; height: 6px;">
        <div style="width: ${task.progress}%; background: #60A5FA; height: 100%; border-radius: 4px;"></div>
      </div>
      <div style="font-size: 11px; margin-top: 4px; color: #94A3B8;">${task.progress}% complete</div>
    </div>
  `,
})

Showing assignees

When tasks include an assignees array, render them in the tooltip:

const gantt = new ApexGantt(el, {
  series: tasks,
  tooltipTemplate: (task) => {
    const assigneeHtml = (task.assignees ?? [])
      .map(a => `<span title="${escapeHtml(a.name)}" style="
        display:inline-flex; align-items:center; justify-content:center;
        width:24px; height:24px; border-radius:50%; background:${a.color ?? '#64748B'};
        color:#fff; font-size:10px; font-weight:600;
      ">${escapeHtml(a.initials ?? a.name.slice(0,2).toUpperCase())}</span>`)
      .join('')

    return `
      <div style="padding: 10px 14px; min-width: 200px;">
        <div style="font-weight: 600; margin-bottom: 6px;">${escapeHtml(task.name)}</div>
        <div style="font-size: 12px; color: #64748B;">
          ${task.startTime} → ${task.endTime}
        </div>
        ${assigneeHtml ? `<div style="margin-top:8px; display:flex; gap:4px;">${assigneeHtml}</div>` : ''}
      </div>
    `
  },
})

Suppressing the tooltip

To turn task tooltips off, set enableTooltip: false. Returning an empty string from tooltipTemplate also hides it; the container still exists in the DOM but is invisible:

enableTooltip: false,
// or
tooltipTemplate: () => '',

React example

import { ApexGanttChart } from 'react-apexgantt'
import type { Task, GanttUserOptions } from 'react-apexgantt'
import { escapeHtml } from 'apexgantt'

function buildTooltip(task: Task): string {
  return `
    <div style="padding:10px 14px;min-width:200px">
      <div style="font-weight:600;margin-bottom:6px">${escapeHtml(task.name)}</div>
      <div style="font-size:12px">
        <div>${task.startTime} → ${task.endTime}</div>
        <div style="margin-top:4px">${task.progress}% complete</div>
        ${task.wbs ? `<div style="color:#64748B;margin-top:2px">WBS: ${escapeHtml(task.wbs)}</div>` : ''}
      </div>
    </div>
  `
}

const options: Omit<GanttUserOptions, 'series'> = {
  tooltipBGColor: '#FFFFFF',
  tooltipBorderColor: '#E2E8F0',
  tooltipTemplate: buildTooltip,
}

export default function TooltipGantt() {
  return <ApexGanttChart tasks={tasks} options={options} height="500px" />
}

Vue example

<template>
  <ApexGanttChart :tasks="tasks" :options="ganttOptions" height="500px" />
</template>

<script setup lang="ts">
import type { GanttUserOptions, Task } from 'vue-apexgantt'
import { escapeHtml } from 'apexgantt'

const ganttOptions: Partial<GanttUserOptions> = {
  tooltipBGColor: '#FFFFFF',
  tooltipBorderColor: '#E2E8F0',
  tooltipTemplate: (task: Task) => `
    <div style="padding:10px 14px;min-width:200px">
      <div style="font-weight:600;margin-bottom:6px">${escapeHtml(task.name)}</div>
      <div style="font-size:12px">${task.startTime} → ${task.endTime}</div>
      <div style="font-size:12px">${task.progress}% complete</div>
    </div>
  `,
}
</script>