Progress Tracking
ApexGantt renders a filled portion inside each task bar to represent completion. The progress field on a task accepts a value from 0 to 100. This page covers how to display, edit, and listen for progress changes.
Setting initial progress
Pass progress on each TaskInput. It defaults to 0 when omitted:
const tasks = [
{
id: 'task-1',
name: 'Design',
startTime: '2024-03-01',
endTime: '2024-03-15',
progress: 100, // complete
},
{
id: 'task-2',
name: 'Development',
startTime: '2024-03-16',
endTime: '2024-04-15',
progress: 45, // in progress
},
{
id: 'task-3',
name: 'QA',
startTime: '2024-04-16',
endTime: '2024-04-30',
progress: 0, // not started
},
]
Interactive progress drag
enableProgressDrag: true adds a drag handle at the bottom edge of each task bar. The user drags it left or right to set completion. The value snaps to whole percents on commit.
const gantt = new ApexGantt(document.getElementById('chart'), {
inputDateFormat: 'YYYY-MM-DD', // the dates above are ISO
series: tasks,
enableProgressDrag: true, // the default
})
gantt.render()
taskProgressChanged event
When the user drags the progress handle, taskProgressChanged fires after the value commits. Like every Gantt event it is dispatched on the container element you passed to the constructor:
document.getElementById('chart').addEventListener('taskProgressChanged', (e) => {
const { taskId, oldProgress, newProgress } = e.detail
console.log(`${taskId}: ${oldProgress}% → ${newProgress}%`)
// save to backend
})
Event detail payload
| Field | Type | Description |
|---|---|---|
taskId | string | ID of the task whose progress changed |
oldProgress | number | Previous completion value (0 to 100) |
newProgress | number | New completion value (0 to 100) |
timestamp | number | Date.now() at the time of the event |
Progress drag is recorded in the undo history automatically: undo() restores the previous value. Since 3.20.0 a progress drag also fires taskUpdate and taskUpdateSuccess with source: 'progress', so listen to one or the other when saving, not both.
Programmatic progress update
Call updateTask() to set progress from code, for example after polling a backend or receiving a WebSocket event:
// mark a single task done
gantt.updateTask('task-2', { progress: 100 })
// bulk update from API response
apiTasks.forEach(({ id, percentComplete }) => {
gantt.updateTask(id, { progress: percentComplete })
})
updateTask() accepts any partial TaskInput fields and re-renders without a full chart rebuild. Since 3.20.0 the change is stored even when the task's row is not rendered (under a collapsed parent, filtered out, or outside the virtualized window past 50 rows); before 3.20.0 such an update was lost.
Showing progress in the task list
Add a progress or progressRing column to columnConfig to display the value alongside the task name:
const gantt = new ApexGantt(el, {
series: tasks,
columnConfig: [
{ key: 'name', title: 'Task', minWidth: '180px', flexGrow: 3 },
{ key: 'startTime', title: 'Start', minWidth: '100px', flexGrow: 1 },
{ key: 'endTime', title: 'End', minWidth: '100px', flexGrow: 1 },
{ key: 'progress', title: '%', minWidth: '60px', flexGrow: 0 },
{ key: 'progressRing',title: '', minWidth: '36px', flexGrow: 0 },
],
})
progress renders the numeric value as text (e.g. 45%). progressRing renders a circular indicator.
Custom progress column
Use a render function to build a bar-style progress indicator in the task list:
{
key: 'progressBar',
title: 'Progress',
minWidth: '120px',
flexGrow: 2,
render: (ctx) => {
const pct = ctx.task.progress
const color = pct === 100 ? '#10B981' : pct > 0 ? '#3B82F6' : '#E5E7EB'
return `
<div style="display:flex;align-items:center;gap:8px;width:100%">
<div style="flex:1;background:#F1F5F9;border-radius:4px;height:6px;overflow:hidden">
<div style="width:${pct}%;background:${color};height:100%;border-radius:4px;transition:width .2s"></div>
</div>
<span style="font-size:11px;color:#64748B;white-space:nowrap">${pct}%</span>
</div>
`
},
accessor: (task) => task.progress,
},
Validating progress changes
Use beforeTaskUpdate to intercept a progress change before it commits. The hook receives one object, { task, updates }. Since 3.20.0 it runs for progress drags too; before 3.20.0 it ran only for updateTask() and inline edits.
const gantt = new ApexGantt(el, {
series: tasks,
enableProgressDrag: true,
beforeTaskUpdate: ({ task, updates }) => {
// prevent reducing progress (no going backwards)
if (updates.progress !== undefined && updates.progress < task.progress) {
return false
}
return true
},
})
A vetoed drag is repainted from the data, and no event fires.
Real-time progress from a server
Poll or subscribe and push updates to the chart without triggering a full re-render:
const gantt = new ApexGantt(el, { series: tasks })
// WebSocket example
const ws = new WebSocket('wss://api.example.com/gantt-events')
ws.addEventListener('message', (e) => {
const { taskId, progress } = JSON.parse(e.data)
// silent (3.20.0+): do not fire taskUpdate / taskUpdateSuccess for a change
// that came from the server, so a save handler does not send it back
gantt.updateTask(taskId, { progress }, { silent: true })
})
React example
import { ApexGanttChart } from 'react-apexgantt'
import type { GanttUserOptions } from 'react-apexgantt'
import type { TaskProgressChangedEventDetail } from 'apexgantt'
const options: Omit<GanttUserOptions, 'series'> = {
inputDateFormat: 'YYYY-MM-DD',
enableProgressDrag: true,
columnConfig: [
{ key: 'name', title: 'Task', minWidth: '180px', flexGrow: 3 },
{ key: 'progressRing', title: '', minWidth: '36px', flexGrow: 0 },
{ key: 'progress', title: '%', minWidth: '60px', flexGrow: 0 },
],
}
export default function ProgressGantt() {
const onProgressChanged = ({ taskId, newProgress }: TaskProgressChangedEventDetail) => {
// persist to backend
fetch(`/api/tasks/${taskId}`, {
method: 'PATCH',
body: JSON.stringify({ progress: newProgress }),
headers: { 'Content-Type': 'application/json' },
})
}
return (
<ApexGanttChart
tasks={tasks}
options={options}
height="500px"
onTaskProgressChanged={onProgressChanged}
/>
)
}
onTaskProgressChanged needs react-apexgantt built for apexgantt 3.20.0, which exposes every core event as an on* prop. On older wrapper versions, wrap the chart in your own element and listen for taskProgressChanged there: Gantt events bubble.
Vue example
<template>
<ApexGanttChart
:tasks="tasks"
:options="ganttOptions"
height="500px"
@task-progress-changed="onProgressChanged"
/>
</template>
<script setup lang="ts">
import type { GanttUserOptions } from 'vue-apexgantt'
const ganttOptions: Partial<GanttUserOptions> = {
inputDateFormat: 'YYYY-MM-DD',
enableProgressDrag: true,
columnConfig: [
{ key: 'name', title: 'Task', minWidth: '180px', flexGrow: 3 },
{ key: 'progressRing', title: '', minWidth: '36px', flexGrow: 0 },
{ key: 'progress', title: '%', minWidth: '60px', flexGrow: 0 },
],
}
const onProgressChanged = (detail: { taskId: string; newProgress: number }) => {
console.log(`${detail.taskId}: now ${detail.newProgress}%`)
// persist to backend
}
</script>
The task-progress-changed event needs vue-apexgantt built for apexgantt 3.20.0, which emits every core event.