Annotations

Annotations overlay vertical markers and shaded regions on the timeline. 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'), {
  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 (ISO 8601 or any format ApexGantt parses)
x2	string | null	—	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	0	SVG stroke-dasharray value
borderWidth	number	annotationBorderWidth	Border line width in pixels
label	AnnotationLabel	—	Optional label drawn at the annotation

Label styling

Property	Type	Description
text	string	The label text
fontColor	string	Text color
fontFamily	string	Font family
fontSize	string	Font size (e.g. '12px')
fontWeight	string	Font weight (e.g. '600')
orientation	'horizontal' | 'vertical'	Label orientation; horizontal is default

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	'#F9D1FC'	Background color for all range annotations
annotationBorderColor	string	'#E273EA'	Border/line color for all annotations
annotationBorderDashArray	number[]	[]	SVG stroke-dasharray for all annotation borders
annotationBorderWidth	number	2	Border width in pixels
annotationOrientation	'horizontal' | 'vertical'	'horizontal'	Orientation of all annotation labels

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.

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.

const gantt = new ApexGantt(el, {
  series: tasks,
  enableProjectBoundary: true,
  projectBoundaryColor: '#7C3AED',   // default: '#7C3AED'
})

The boundary lines respond to runtime mutations (addTask, deleteTask, drag, resize) without needing a manual update() call.

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 }}
      viewMode="week"
      height="500px"
    />
  )
}

Vue example

<template>
  <ApexGanttChart
    :tasks="tasks"
    :options="ganttOptions"
    view-mode="week"
    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>