Row Grouping and Hierarchy
ApexGantt supports multi-level task hierarchies through parentId. Parent rows automatically compute their date span from their children and display as summary (group) bars. This page covers how to structure hierarchical data, control the summary bar appearance, and use rollup markers.
Building a hierarchy with parentId
Set parentId on a task to nest it under another task. The parent task displays a summary bar spanning the earliest child start to the latest child end:
const tasks = [
{
id: 'phase-1',
name: 'Phase 1: Research',
startTime: '2024-03-01',
endTime: '2024-03-31',
},
{
id: 'task-1-1',
name: 'User Interviews',
startTime: '2024-03-01',
endTime: '2024-03-10',
progress: 100,
parentId: 'phase-1',
},
{
id: 'task-1-2',
name: 'Competitive Analysis',
startTime: '2024-03-11',
endTime: '2024-03-20',
progress: 80,
parentId: 'phase-1',
},
{
id: 'task-1-3',
name: 'Requirements Doc',
startTime: '2024-03-21',
endTime: '2024-03-31',
progress: 40,
parentId: 'phase-1',
},
{
id: 'phase-2',
name: 'Phase 2: Design',
startTime: '2024-04-01',
endTime: '2024-04-30',
dependency: 'phase-1',
},
{
id: 'task-2-1',
name: 'Wireframes',
startTime: '2024-04-01',
endTime: '2024-04-15',
progress: 20,
parentId: 'phase-2',
},
]
const gantt = new ApexGantt(document.getElementById('chart'), {
inputDateFormat: 'YYYY-MM-DD', // the dates on this page are ISO
series: tasks,
})
Hierarchy depth is unlimited. Any task can be both a child of one task and a parent of others. Siblings are sorted by start date by default, not by array order; pass sortBy: [] to keep the order of series.
A parent row may omit startTime and endTime, since its bar is computed from its children. Since 3.20.0 such a row is also kept by parsing when it is the parent of a dated row (directly or further down); any other row with no start date is skipped with a warning. A parent with only an endTime, or with a startTime and no endTime, is drawn as a summary bar spanning its children.
Every parentId should match the id of a task in series. It is compared by value, so '1' finds a task whose id is the number 1. A parentId that matches no task, or that makes a cycle (a task naming itself, or a under b under a), logs a warning and the task is shown at the root; before 3.20.0 a cycle overflowed the stack.
Summary bars
Any task with children renders as a summary bar by default: showSummaryBar defaults to true for a parent, so its own startTime and endTime are ignored and the bar spans the earliest start to the latest end of its descendants. Set showSummaryBar: false on a parent to draw its own dates as a normal bar instead:
{
id: 'phase-1',
name: 'Phase 1: Research',
startTime: '2024-03-01', // used, because showSummaryBar is false
endTime: '2024-03-31',
showSummaryBar: false, // opt out of the computed summary bar
},
A summary bar is read-only: drag, resize, and progress editing are disabled on it, and it recomputes whenever a child changes. Clicking it expands or collapses its children. With showSummaryBar: false the parent row is an ordinary, editable bar.
The summary bar uses summaryBarColor for its fill:
const gantt = new ApexGantt(el, {
series: tasks,
summaryBarColor: '#475569', // default: '#94A3B8' (light theme), '#8FBCBC' (dark theme)
})
Collapsed state
Set collapsed: true on a parent task to start with its children hidden. The user can expand/collapse interactively:
{
id: 'phase-2',
name: 'Phase 2: Design',
startTime: '2024-04-01',
endTime: '2024-04-30',
showSummaryBar: true,
collapsed: true, // children hidden on initial render
},
collapsed is a mutable field: the chart updates it internally as the user expands and collapses rows without needing an external re-render.
To open or close a parent from code, call expandTask(id) or collapseTask(id) (3.20.0+). They change view state only: nothing is recorded in undo history, and the result is saved with the rest of the view state like setState({ collapsed }). Both return false for an unknown id or a task with no children. Since 3.20.0 updateTask(id, { collapsed }) also re-renders at once; before 3.20.0 it changed the data without redrawing the rows.
gantt.expandTask('phase-2')
gantt.collapseTask('phase-1')
Rollup markers
enableRollups: true draws small thin markers below each summary bar at the date position of each leaf descendant. The markers remain visible even when the parent is collapsed, giving a compact overview of the subtree schedule without expanding it:
const gantt = new ApexGantt(el, {
series: tasks,
enableRollups: true,
})
Grouping by a field
Beyond the parentId tree, ApexGantt can bucket tasks under collapsible group headers by any column value. While grouping is active the parent/child tree is suspended and every task appears flat under its group header (label plus member count); clearing it restores the exact prior hierarchy. Grouping is view-only, so it never mutates the task tree or data, and it composes with sorting and filtering.
Set it at construction with the groupBy option:
const gantt = new ApexGantt(el, { series: tasks, groupBy: ColumnKey.Progress })
Or drive it at runtime:
gantt.groupBy(ColumnKey.Progress)
// customize how the value is extracted, labelled, and ordered
gantt.groupBy({
field: 'status',
label: (value) => `Status: ${value}`,
direction: 'desc',
})
gantt.clearGrouping() // restore the tree
Every group change emits a groupChange event with { active, field, groupCount, timestamp }.
Since 3.20.0 group headers are ordered by the underlying value, so numbers sort numerically and dates chronologically, and the "(None)" group for empty values stays last. Before 3.20.0 they were ordered by their label text, so 10 came before 9.
Since 3.20.0, grouping by Duration uses the count the Duration column shows, so with hour or minute snapping you get groups such as 4 h and 8 h instead of a single 0 d group, and with a calendar the groups are working days.
GroupCriterion
| Property | Type | Description |
|---|---|---|
field | ColumnKey | string | Column key whose value tasks are grouped by |
accessor | (task) => unknown | Overrides the column's accessor for extracting the group value |
label | (value) => string | Formats a raw group value into the header label (defaults to String(value)) |
direction | 'asc' | 'desc' | Order of the group headers (default 'asc') |
When state is persisted, only field and direction are stored; a restored grouping falls back to the column's own accessor because accessor and label functions are not serializable.
WBS codes
When tasks are arranged in a hierarchy, ApexGantt computes Work Breakdown Structure codes automatically (e.g. '1', '1.1', '1.2', '2', '2.1.1'). Show them in the task list by adding the wbs column:
columnConfig: [
{ key: 'wbs', title: '#', minWidth: '60px', flexGrow: 0 },
{ key: 'name', title: 'Task', minWidth: '180px', flexGrow: 3 },
{ key: 'startTime', title: 'Start', minWidth: '100px', flexGrow: 1 },
{ key: 'endTime', title: 'End', minWidth: '100px', flexGrow: 1 },
],
WBS codes are recomputed whenever the tree structure changes (add, delete, move, indent, outdent).
Adding child tasks programmatically
Pass parentId in the second argument to addTask():
gantt.addTask(
{
id: 'task-new',
name: 'New subtask',
startTime: '2024-04-16',
endTime: '2024-04-20',
},
{ parentId: 'phase-2' },
)
Moving tasks between parents
// promote to root
gantt.moveTask('task-1-1', { newParentId: null })
// reparent to a different group
gantt.moveTask('task-1-1', { newParentId: 'phase-2' })
moveTask() recomputes WBS codes, summary dates, and critical path markers automatically.
Full example
const gantt = new ApexGantt(document.getElementById('chart'), {
inputDateFormat: 'YYYY-MM-DD',
series: [
{
id: 'phase-1',
name: 'Phase 1',
startTime: '2024-03-01',
endTime: '2024-03-31',
showSummaryBar: true,
},
{
id: 'task-1-1',
name: 'Research',
startTime: '2024-03-01',
endTime: '2024-03-15',
progress: 100,
parentId: 'phase-1',
},
{
id: 'task-1-2',
name: 'Spec Writing',
startTime: '2024-03-16',
endTime: '2024-03-31',
progress: 60,
parentId: 'phase-1',
},
{
id: 'phase-2',
name: 'Phase 2',
startTime: '2024-04-01',
endTime: '2024-04-30',
showSummaryBar: true,
collapsed: true,
dependency: 'phase-1',
},
{
id: 'task-2-1',
name: 'Implementation',
startTime: '2024-04-01',
endTime: '2024-04-25',
progress: 0,
parentId: 'phase-2',
},
],
summaryBarColor: '#334155',
enableRollups: true,
columnConfig: [
{ key: 'wbs', title: '#', minWidth: '60px', flexGrow: 0 },
{ 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 },
],
})
React example
import { ApexGanttChart } from 'react-apexgantt'
import type { TaskInput, GanttUserOptions } from 'react-apexgantt'
const tasks: TaskInput[] = [
{ id: 'p1', name: 'Phase 1', startTime: '2024-03-01', endTime: '2024-03-31', showSummaryBar: true },
{ id: 't1', name: 'Research', startTime: '2024-03-01', endTime: '2024-03-15', progress: 100, parentId: 'p1' },
{ id: 't2', name: 'Spec Writing', startTime: '2024-03-16', endTime: '2024-03-31', progress: 60, parentId: 'p1' },
{ id: 'p2', name: 'Phase 2', startTime: '2024-04-01', endTime: '2024-04-30', showSummaryBar: true, dependency: 'p1' },
{ id: 't3', name: 'Build', startTime: '2024-04-01', endTime: '2024-04-25', progress: 0, parentId: 'p2' },
]
const options: Omit<GanttUserOptions, 'series'> = {
inputDateFormat: 'YYYY-MM-DD',
summaryBarColor: '#334155',
enableRollups: true,
columnConfig: [
{ key: 'wbs', title: '#', minWidth: '60px', flexGrow: 0 },
{ key: 'name', title: 'Task', minWidth: '180px', flexGrow: 3 },
],
}
export default function HierarchyGantt() {
return <ApexGanttChart tasks={tasks} options={options} pixelsPerDay={25.7} height="500px" />
}
Vue example
<template>
<ApexGanttChart :tasks="tasks" :options="ganttOptions" :pixels-per-day="25.7" height="500px" />
</template>
<script setup lang="ts">
import type { GanttUserOptions, TaskInput } from 'vue-apexgantt'
const tasks: TaskInput[] = [
{ id: 'p1', name: 'Phase 1', startTime: '2024-03-01', endTime: '2024-03-31', showSummaryBar: true },
{ id: 't1', name: 'Research', startTime: '2024-03-01', endTime: '2024-03-15', progress: 100, parentId: 'p1' },
{ id: 't2', name: 'Design', startTime: '2024-03-16', endTime: '2024-03-31', progress: 40, parentId: 'p1' },
]
const ganttOptions: Partial<GanttUserOptions> = {
inputDateFormat: 'YYYY-MM-DD',
summaryBarColor: '#334155',
enableRollups: true,
}
</script>