Annotations
Annotations overlay vertical markers and shaded regions on the timeline. The line or region runs down the task rows. Use them to call out deadlines, sprints, milestones, holidays, or any point or range in time that the viewer should notice.
Point annotation
A point annotation draws a vertical line at a single date. Set x1 to the date and omit x2:
const gantt = new ApexGantt(document.getElementById('chart'), {
inputDateFormat: 'YYYY-MM-DD', // annotation dates use the same format as task dates
series: tasks,
annotations: [
{
x1: '2024-04-01',
label: { text: 'Go-live' },
},
],
})
Range annotation
Set both x1 and x2 to shade a region between two dates:
const gantt = new ApexGantt(el, {
series: tasks,
annotations: [
{
x1: '2024-03-01',
x2: '2024-03-15',
label: { text: 'Sprint 1' },
},
{
x1: '2024-03-18',
x2: '2024-03-29',
label: { text: 'Sprint 2' },
},
],
})
Annotation interface
| Property | Type | Default | Description |
|---|---|---|---|
x1 | string | Required | Start date, parsed with inputDateFormat (ISO dates also parse through a lenient fallback) |
x2 | string | null | None | End date. When set, a shaded region is drawn between x1 and x2. |
bgColor | string | annotationBgColor | Background fill for this annotation (overrides the global default) |
borderColor | string | annotationBorderColor | Border / line color for this annotation |
borderDashArray | number | number[] | annotationBorderDashArray | SVG stroke-dasharray value, e.g. 4 or [6, 3]. 0 or [] draws it solid. The array form is accepted since 3.20.0. The gaps of a dashed line are left empty |
borderWidth | number | annotationBorderWidth | Border line width in pixels |
label | AnnotationLabel | None | Optional label drawn at the annotation |
Label styling
| Property | Type | Description |
|---|---|---|
text | string | The label text |
fontColor | string | Text color |
fontFamily | string | Font family. When unset, the chart's font (--apex-gantt-font-family, else fontFamily) |
fontSize | string | Font size (e.g. '12px'). When unset, the chart's size (--apex-gantt-font-size, else fontSize) |
fontWeight | string | Font weight (e.g. '600') |
orientation | 'horizontal' | 'vertical' | Label orientation. Falls back to annotationOrientation (default 'horizontal'). It turns only the label; the line or region still runs down the task rows |
Since 3.20.0 borderDashArray and label.orientation are drawn, per annotation and through the global annotationBorderDashArray / annotationOrientation options. Earlier versions accepted them but always drew a solid border and a horizontal label. borderWidth, borderColor and bgColor work in every version.
A dashed line annotation (a dash pattern and no x2) has an empty background, so the timeline shows through its gaps. A range annotation keeps its fill.
Since 3.20.0 an annotation label that sets no fontFamily or fontSize of its own follows the --apex-gantt-font-family and --apex-gantt-font-size custom properties when they are set on the container; before, it used the fontFamily and fontSize options even then.
const gantt = new ApexGantt(el, {
series: tasks,
annotations: [
{
x1: '2024-06-15',
borderColor: '#EF4444',
borderWidth: 2,
label: {
text: 'Deadline',
fontColor: '#EF4444',
fontWeight: '700',
fontSize: '12px',
},
},
],
})
Global annotation defaults
Set defaults for all annotations at once using top-level options. Per-annotation properties override these when present:
| Option | Type | Default | Description |
|---|---|---|---|
annotationBgColor | string | '#DBEAFE' (dark theme '#4A2D4D') | Background color for all range annotations |
annotationBorderColor | string | '#60A5FA' (dark theme '#8B4D8F') | Border/line color for all annotations |
annotationBorderDashArray | number[] | [] | SVG stroke-dasharray for all annotation borders (drawn since 3.20.0) |
annotationBorderWidth | number | 2 | Border width in pixels |
annotationOrientation | 'horizontal' | 'vertical' | 'horizontal' | Orientation of all annotation labels (applied since 3.20.0) |
const gantt = new ApexGantt(el, {
series: tasks,
annotationBgColor: '#DBEAFE',
annotationBorderColor: '#3B82F6',
annotationBorderWidth: 1,
annotations: [
{ x1: '2024-03-01', x2: '2024-03-15', label: { text: 'Sprint 1' } },
{ x1: '2024-03-18', x2: '2024-03-29', label: { text: 'Sprint 2' } },
// these inherit the global blue styling
],
})
Mixed styles
Combine global defaults with per-annotation overrides to create visual variety:
const gantt = new ApexGantt(el, {
series: tasks,
annotationBgColor: '#DBEAFE',
annotationBorderColor: '#3B82F6',
annotations: [
// inherits global blue
{ x1: '2024-03-01', x2: '2024-03-15', label: { text: 'Sprint 1' } },
// red for a deadline
{
x1: '2024-04-01',
borderColor: '#EF4444',
bgColor: '#FEE2E2',
label: { text: 'Deadline', fontColor: '#EF4444' },
},
],
})
Updating annotations at runtime
Call update() to replace the annotations array after mount:
gantt.update({
annotations: [
{ x1: '2024-05-01', label: { text: 'Phase 2 start' } },
{ x1: '2024-05-01', x2: '2024-05-31', label: { text: 'May Sprint' } },
],
})
update() does a shallow merge with the existing options, so only the keys you pass are replaced. Since 3.20.0 it also keeps the current task data, including edits made in the chart; on 3.19 and earlier any update() rebuilt the tasks from the original series.
Project boundary lines
enableProjectBoundary: true draws two automatic vertical lines: one at the earliest task start and one at the latest task end. The lines update automatically as tasks are added, removed, or rescheduled. Each line carries the CSS class annotation--project-boundary, so you can style or hide the pair without touching your own annotations.
const gantt = new ApexGantt(el, {
series: tasks,
enableProjectBoundary: true,
projectBoundaryColor: '#7C3AED', // default: '#7C3AED'
})
Since 3.20.0 the lines follow every edit: a drag, a resize, a keyboard move, updateTask(), the edit dialog, an inline edit, and undo or redo of any of these move them at once, as do addTask(), deleteTask(), moveTask() and update(). On 3.19 and earlier the lines were recomputed only on a full render, so a drag, resize or updateTask() that moved the project's first start or last end left them where they were until the next full render.
React example
import { useState } from 'react'
import { ApexGanttChart } from 'react-apexgantt'
import type { GanttUserOptions } from 'react-apexgantt'
const baseOptions: Omit<GanttUserOptions, 'series'> = {
annotationBgColor: '#DBEAFE',
annotationBorderColor: '#3B82F6',
annotationBorderWidth: 1,
enableProjectBoundary: true,
}
export default function AnnotatedGantt() {
const [annotations, setAnnotations] = useState([
{ x1: '2024-03-01', x2: '2024-03-15', label: { text: 'Sprint 1' } },
{ x1: '2024-03-18', x2: '2024-03-29', label: { text: 'Sprint 2' } },
{
x1: '2024-04-01',
borderColor: '#EF4444',
bgColor: '#FEE2E2',
label: { text: 'Go-live', fontColor: '#EF4444', fontWeight: '700' },
},
])
return (
<ApexGanttChart
tasks={tasks}
options={{ ...baseOptions, annotations }}
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 } from 'vue-apexgantt'
const ganttOptions: Partial<GanttUserOptions> = {
annotationBgColor: '#DBEAFE',
annotationBorderColor: '#3B82F6',
enableProjectBoundary: true,
annotations: [
{ x1: '2024-03-01', x2: '2024-03-15', label: { text: 'Sprint 1' } },
{
x1: '2024-04-01',
borderColor: '#EF4444',
label: { text: 'Go-live', fontColor: '#EF4444' },
},
],
}
</script>