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):
| Field | Type | Description |
|---|---|---|
durationText | string | The 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 |
messages | GanttMessages | Since 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 / endText | string | Since 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 |
tag | string | Since 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:
| Field | Type | Description |
|---|---|---|
id | string | Unique task identifier |
name | string | Display name |
startTime | string | Start date string |
endTime | string | End date string (always present after normalisation) |
progress | number | Completion percentage (0 to 100) |
type | TaskType | 'task' or 'milestone' |
showSummaryBar | boolean | undefined | true on a parent drawn as a summary bar |
summaryStart / summaryEnd | string | undefined | Computed span of a summary bar |
parentId | string | undefined | Parent task ID |
wbs | string | undefined | Work Breakdown Structure code (e.g. '1.2.3') |
level | number | undefined | Nesting depth (1 = top-level) |
barBackgroundColor | string | undefined | Per-task bar color override |
assignees | Assignee[] | Assigned people (if set on the task) |
baseline | BaselineInput | undefined | Planned start/end if set |
left | number | undefined | Computed x-offset in the timeline (pixels) |
width | number | undefined | Computed 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>