Options

Color theme preset. Switching it at runtime with update({ theme }) replaces colour options with the new theme's defaults; see update() for what a theme change keeps.

Available Options:

• light (default)
• dark
• Since 3.21.0, the name of a theme registered on the registry the Apex products share (registerTheme from apex-commons, or ApexCharts.registerTheme). Its tokens rank below the --apx-* tokens and above the design system, and its mode: 'dark' picks the dark colours (light otherwise).

Left unset, the chart follows a page design system that declares a dark variant (Ignite UI's --ig-theme-variant: dark, with the apexgantt/ignite-ui add-on loaded) until the variant changes. A theme you pass is always kept. Since 3.21.0 update({ theme: undefined }) returns the chart to no theme (light, or the design system's dark variant); before, a dark chart stayed dark.

Since 3.21.0. Read the --apx-* tokens the Apex products share, and the page's design system. Set false to stop the chart reading both, including the design system's light or dark variant. Options and --apex-gantt-* CSS variables still apply. Defaults to true. See Using with Ignite UI.

Since 3.21.0. Follow the page's design system: Ignite UI's --ig-* tokens, including its light or dark variant. Has an effect only while the apexgantt/ignite-ui add-on is loaded; without it the chart reads no design system. It ranks below everything else you set. Set false to turn this layer off for this chart and keep the --apx-* tokens; tokens: false turns it off as well. Defaults to true. See Using with Ignite UI.

Width of the chart. Accepts a pixel number or a CSS string.

Height of the chart. Accepts a pixel number or a CSS string. Defaults to '500px'.

Since 3.20.0, when height is not set and the container element already has a height of its own (from CSS or an inline style), the chart fills the container and follows its size as it changes. Before 3.20.0 the 500px default was written inline and overrode the container's height, so set height explicitly on those versions.

Arbitrary CSS injected onto the root container element.

Initial zoom level expressed as pixels per day. Continuous: the timeline header automatically picks calendar tiers (year, quarter, month, week, day, halfday, hour, minute) based on the current value. Bounds are clamped to roughly [0.25, 7680] px/day.

Reference values calibrated against the legacy presets:

• Year ≈ 0.5
• Quarter ≈ 1.6
• Month ≈ 4.9
• Week ≈ 25.7
• Day = 80

When omitted, the chart auto-fits the full data range into the visible timeline area on first render. Supply an explicit value (or use the toolbar zoom controls) to take control.

Background color of the whole chart container.

Background color of the timeline and task-list header row.

Color of the cell and row divider lines.

Border color for all cells in the task table and timeline grid.

CSS border-width for all cell lines.

Whether to draw vertical lines between timeline columns. Set to false for a cleaner aesthetic that keeps only the horizontal row dividers.

Available Options:

• true (default)
• false

dayjs-compatible format string used to parse startTime / endTime values, and the format edited dates are written back in. Include time tokens (e.g. 'YYYY-MM-DD HH:mm') to enable sub-day scheduling; end-times are then treated as exclusive timestamps and inline editors switch to datetime-local inputs. Set it to match your data: ISO dates under the default 'MM-DD-YYYY' still draw through a lenient fallback, but edits are written back as MM-DD-YYYY.

Since 3.22.0 the format reads more tokens: Q, Do, k, X, x, w/ww/wo, W/WW, gggg/GGGG and L/LL/LLL/LLLL with their lowercase forms. A format that held one of those letters as literal text now prints a value there (Q the quarter, k the hour), so wrap literal text in [ ]; the chart logs one warning when it finds such a letter outside brackets. The default 'MM-DD-YYYY' is unaffected. To show dates differently from how they are parsed, set locale.displayDateFormat.

Initial pixel width of the task-list panel.

Allow the task-list panel to be resized by dragging the divider.

Show the export button in the toolbar. The format it produces is set by exportFormat.

Format the toolbar export button produces. Any format is also available programmatically through gantt.exportChart(format).

Available Options:

• svg (default): vector output
• png: rasterized image
• pdf: single-page, image-based, dependency-free

Size each task-list column to fit its header title and widest cell content, growing the task-list panel (never below tasksContainerWidth) so nothing is clipped. flexGrow still distributes any extra width, minWidth acts as a floor, and maxWidth (per column) as the ceiling. Set false to distribute the panel width purely by flexGrow.

Available Options:

• true (default)
• false

Allow task-list columns to be resized by dragging the handle at the trailing edge of a column header. A resized column is pinned to its chosen pixel width and the others absorb the remaining space. Double-click a handle to reset that column to auto width. Opt a single column out with columnConfig[].resizable: false.

Available Options:

• true (default)
• false

Allow columns to be reordered by dragging a column header left or right onto another column. A vertical drop indicator shows the insertion point. The new order is captured by getState() / setState() and emitted as a columnReorder event.

Available Options:

• true (default)
• false

Initial sort applied to the task list, as one SortCriterion or an array of them. When omitted, rows are sorted by start time, ascending, so the task list does not follow the order of series; pass [] for natural (input) order. Sorting is hierarchy-preserving: siblings reorder within each parent and the tree is never flattened. With multiple criteria the first key wins and ties break on the next. Since 3.20.0, tasks with an empty value sort last in both directions. See the Sorting and Filtering guide.

sortBy: { key: ColumnKey.Name, direction: 'asc' }
sortBy: [{ key: ColumnKey.Progress, direction: 'desc' }, { key: ColumnKey.Name }]

Column to sort by. A ColumnKey value for built-in columns or a custom column id.

Sort direction for this criterion.

Available Options:

• asc (default)
• desc

Initial predicate filter run against each task. A task is kept when it matches or has a matching descendant, so ancestors of matches stay visible. View-only: it changes which rows render, never the tree, WBS, or task data.

filterBy: (task) => task.progress < 100

Initial structured filter for the advanced filter builder: a FilterRuleSet of conditions combined with 'all' (AND) or 'any' (OR). Takes precedence over filterBy when both are set.

filterRules: {
  match: 'all',
  rules: [{ field: 'progress', operator: 'lt', value: 100 }],
}

How the rules combine.

Available Options:

• all: every rule must match (AND)
• any: at least one rule must match (OR)

The conditions to evaluate. An empty list means no filter.

Column key whose value is tested, either a ColumnKey or a custom column id.

Comparison operator applied to the field value.

Available Options:

• contains
• notContains
• equals
• notEquals
• startsWith
• endsWith
• gt
• gte
• lt
• lte
• before
• after
• on
• isEmpty
• notEmpty

Operand compared against the field: a number for number columns, a YYYY-MM-DD string for date columns, free text otherwise. Ignored by isEmpty and notEmpty.

Show a quick-filter search box in the toolbar that matches task fields as the user types.

Available Options:

• false (default)
• true

Fine-tune the quick filter. placeholder sets the input text (falls back to the localized quickFilterPlaceholder message), fields lists the task string fields matched (default ['name']), and caseSensitive controls case matching (default false).

quickFilter: { placeholder: 'Find a task', fields: ['name'], caseSensitive: false }

Placeholder text for the search input. Falls back to the localized quickFilterPlaceholder message when omitted.

Task string fields matched against the query.

Match the query case-sensitively.

Available Options:

• false (default)
• true

Show the advanced filter builder in the toolbar: a "Filter" button that opens a popover for composing field / operator / value conditions combined with All (AND) or Any (OR). Drives the same view-only filter as gantt.setFilterRules().

Available Options:

• false (default)
• true

Initial grouping applied to the task list, as a column key or a GroupCriterion. When set, the parent/child tree is suspended and every task appears flat under a collapsible group header. Clearing it restores the prior hierarchy. See the Row Grouping guide.

groupBy: ColumnKey.Progress
groupBy: { field: 'status', label: (v) => `Status: ${v}`, direction: 'desc' }

Column key whose value tasks are grouped by. Accepts a ColumnKey or a custom column id.

Extract the raw group value from a task, overriding the column's own accessor. Tasks whose values are equal by String(value) land in the same group.

Format a raw group value into the group header label. Defaults to String(value).

Order of the group headers by key. Defaults to 'asc'. Since 3.20.0 groups are ordered by the underlying value (numbers numerically, dates chronologically) rather than by their label text, and the "(None)" group stays last.

Allow drawing a new task by dragging across empty timeline space. On release a task is created with the swept range snapped to snapUnit / snapValue. A preview bar follows the cursor, a plain click creates nothing, and Escape cancels mid-drag (since 3.20.0 wherever focus is; earlier versions only when focus was inside the chart). Existing bars stay draggable and resizable. Creation runs through the beforeTaskAdd veto hook and is undoable.

Available Options:

• false (default)
• true

Show a chevron at the edge of any row whose bar is scrolled out of the visible timeline window; clicking it jumps the bar into view. Opt-in from 3.15.0 onward (previously true). gantt.scrollToTask() works regardless of this setting.

Available Options:

• false (default)
• true

Clicking a task-list row scrolls that task's bar into view (nearest-edge, both horizontal and vertical), the same as calling gantt.scrollToTask(). Composes with enableSelection, so a single click both selects the row and reveals its bar. Clicks on the selection checkbox, the toggle chevron, and active inline-edit inputs are ignored.

Available Options:

• false (default)
• true

Persist and restore the UI view state (zoom, scroll, sort, filter, collapse, selection, manual column widths, and column order) via localStorage. Pass true for the default key ('apexgantt-state'), or an object { key } to set a custom key. Restored on the first render() and saved (debounced) on every view change. The state is also available programmatically through gantt.getState() / gantt.setState(). See the Saving and Restoring State guide.

persistState: true
persistState: { key: 'project-42-gantt' }

localStorage key the state is saved under. Defaults to 'apexgantt-state'. Give each instance its own key when two Gantts on the same origin need to persist separately.

Color of dependency arrows between tasks. Since 3.21.0 a value you pass wins over a --apex-gantt-dependency-line custom property on the container, even the default value; leave the option out to let the property apply (it reaches the arrows since 3.20.0). In 3.20 the property won over the option.

Default background fill color for task bars. Theme-aware: '#87B7FE' in the light theme, '#818CF8' in the dark theme. A per-task barBackgroundColor wins over it. Since 3.21.0 a value you pass wins over a --apex-gantt-bar-fill custom property on the container, even the default value; leave the option out to let the property apply (it reaches the bars since 3.20.0). In 3.20 the property won over the option. See the Theming guide.

CSS border-radius applied to task bars.

Top and bottom margin inside each row for the task bar in pixels. Defaults to 8.

Text color rendered inside task bars. Since 3.20.0 a task can override it with its own barTextColor field.

Fill color for summary (group) bars. Renders distinct from regular task bars to make the parent/child hierarchy visually obvious. Theme-aware: '#94A3B8' in the light theme, '#8FBCBC' in the dark theme.

Fill color for milestone diamonds. Theme-aware: '#7C3AED' in the light theme, '#A78BFA' in the dark theme.

Per-task bar label. By default the task name renders to the right of the bar so narrow bars don't clip their text. Set position: 'inside' to render centered inside the bar, 'auto' to pick automatically based on bar width, or supply render to compose names with chips, icons, or owner info.

barLabel: {
  position: 'auto',
  render: (task) => `<span>${task.name} · ${task.progress}%</span>`,
}

Where to render the label relative to the bar.

Available Options:

• right (default): rendered immediately to the right of the bar; always visible regardless of bar width
• inside: centered inside the bar; clipped when the bar is narrower than the text
• left: rendered immediately to the left of the bar
• auto: inside when the label fits, otherwise right

Task field whose value populates the label when render is not set.

Custom renderer for the bar label. Receives the resolved task and returns an HTML string (assigned via innerHTML, so escape user input yourself) or an HTMLElement. Returning null or undefined falls back to rendering barLabel.field.

Extra CSS class added to the label element.

Pixels of empty space added to the start of the timeline so left-side labels have room to render without being hidden behind the task-list panel. Auto-defaults to 120 when position is 'left', and 0 otherwise. Set explicitly to 0 to disable the padding.

Alternating row background colors. The pattern cycles automatically.

Height of each task row in pixels.

Allow task bars to be dragged horizontally to reschedule them. Dragging a bar changes its dates; it does not reorder rows (use moveTask() or indent/outdent to change the hierarchy). Drawing dependency links is a separate option, dependencies.editable. Since 3.20.0, ArrowLeft / ArrowRight on a focused bar also move it by one snap unit.

Open the edit dialog (name, start, end, progress) when a task bar is double-clicked, or when Enter or Space is pressed on a focused bar. Summary bars do not open it: clicking one toggles its children. Turns on enableInlineEdit too unless that is set to false.

Allow editing task fields directly in task-list cells. When true, double-clicking a name, startTime, endTime, duration, or progress cell swaps the cell for an input: commit with Enter or blur, cancel with Escape. Summary rows, milestones, and empty rows are not editable. Auto-enabled when enableTaskEdit is true unless explicitly set to false. Since 3.20.0 the Duration editor works in the same base units as the Duration column (see snapValue), and an editor left without a change commits nothing (no update events, no undo step). See the Inline Editing guide.

Available Options:

• false (default)
• true

Allow task bars to be resized by dragging their handles. Since 3.20.0, Shift+ArrowLeft / Shift+ArrowRight on a focused bar resize its end by one snap unit (not on milestones).

Allow editing task progress by dragging the small handle at the bottom of the bar. The handle becomes visible on bar hover and snaps to whole percent on commit. Emits a taskProgressChanged event.

Available Options:

• true (default)
• false

Enable keyboard shortcuts for task editing when the task-list panel has focus: Delete / Backspace deletes the focused row (cascade 'children'), Tab / Shift+Tab indent / outdent in the tree. Off by default. See the Inline Editing guide.

Show built-in + Add Task, Delete, and Undo/Redo buttons in the toolbar. The delete button acts on the current selection, so pair it with enableSelection: true. Off by default.

Show a built-in right-click context menu on task bars and task-list rows (Edit, Add child / sibling, Indent, Outdent, Delete). Entries are gated by capability. Off by default.

Show a single-line + Add task row at the bottom of the task list that inserts a new root-level task on click. The row hides while more than 50 rows are visible, because row virtualization is active then; use the toolbar Add button or the context menu instead. Off by default.

Granularity at which task drag, resize, and inline edits snap. Affects data updates only: the timeline header tier follows pixelsPerDay independently. Use 'hour' or 'minute' together with snapValue for sub-day scheduling; end-times are treated as exclusive timestamps when inputDateFormat includes time tokens.

Available Options:

• day (default)
• hour
• minute

Multiplier applied to snapUnit. Examples: snapUnit: 'minute', snapValue: 15 snaps to 15-minute increments; snapUnit: 'hour', snapValue: 6 snaps to 6-hour increments.

Since 3.20.0 the Duration column shows base units: a 45-minute task reads 45 m with snapUnit: 'minute', snapValue: 15. Before 3.20.0 it divided by snapValue and showed 3 m for the same task.

Enable row selection (click, Ctrl+Click, Shift+Click, keyboard). The selection methods (getSelectedTasks, setSelectedTasks, clearSelection) and setState({ selected }) do nothing while this is false; since 3.20.0 they log a one-time console warning in that case.

Show a checkbox column for multi-select. Only applies when enableSelection is true.

When true, calculates and highlights the critical path through dependent tasks.

Fill color for task bars on the critical path (requires enableCriticalPath: true).

Stroke color for dependency arrows on the critical path.

When true, summary (parent) rows display thin rollup markers below the summary bar at each leaf descendant's date range, a glance-able overview of children that stays visible even when the parent is collapsed.

Available Options:

• false (default)
• true

Baseline options. When enabled is true, tasks with a baseline field render a thin bar below the actual bar to show schedule variance.

Whether to render baseline bars below actual bars.

Color of the baseline bar. When striped is true this paints the stripes; otherwise it fills the whole bar. When omitted, the baseline uses the task bar's progress shade (the darker tone of the bar drawn above it), so it reads as the planned twin of its bar.

Fill the baseline bar with diagonal stripes that alternate between color and stripeColor, instead of a flat fill. Default true.

Color of the gaps between stripes. Only used when striped is true. Default '#FFFFFF'.

Width in pixels of each stripe band when striped is true. Larger values produce thicker stripes. Default 3.

Angle in degrees of the stripes when striped is true. Default 45.

Visual and interaction options for dependency arrows. Tune cornerRadius for tighter or looser joints, set hitWidth to add an invisible thicker target zone for hover/click on thin strokes, and use tooltipTemplate / classBuilder for per-arrow content and styling.

dependencies: {
  cornerRadius: 6,
  hitWidth: 12,
  classBuilder: (ctx) => ctx.fromTask.team !== ctx.toTask.team ? 'cross-team' : '',
  tooltipTemplate: (ctx) => `<b>${ctx.fromTask.name}</b> → <b>${ctx.toTask.name}</b>`,
}

Pixel radius for rounded joints on dependency arrows. 0 produces sharp 90° corners; larger values produce smoother arcs (clamped per-corner to half the shorter adjacent segment so an arc never overshoots).

Invisible hit-area thickness in pixels. When greater than 0, each arrow renders an additional transparent path of this width that captures pointer events, making the thin visible stroke easier to hover or click. Required for tooltipTemplate to fire.

Returns CSS class name(s) for each arrow. Receives a DependencyContext (fromTask, toTask, type, lag) and returns a class name string, an array of class names, or undefined. Use to tag arrows by relationship (cross-team, blocked, optional) and style them via custom CSS.

Returns an HTML string shown when the user hovers an arrow. Receives a DependencyContext (fromTask, toTask, type, lag). Requires a non-zero hitWidth so the hover hit area is large enough to register reliably.

Enables interactive editing of dependency arrows. Hovering an arrow darkens it; clicking selects it and shows a remove button at its head, and Delete on a focused arrow removes it, through the same undoable path as removeDependency().

It also enables drawing new links: hovering a bar shows a circle at its start and its finish edge. Drag from a circle onto another bar's start or finish edge; the pair of edges sets the type (finish to start = FS, start to start = SS, finish to finish = FF, start to finish = SF). Since 3.20.0, dropping on the target bar's anchor circle attaches at that anchor, and Escape cancels a link being drawn wherever focus is. When true, hitWidth is raised to at least 12 so the arrows can be clicked.

Whether a dependency may connect a summary task to one of its own descendants. Off by default because a summary's dates come from its descendants, so such links usually indicate a data error. Applies to links drawn by hand (editable: true) and to the programmatic API whether or not editable is set: canAddDependency() reports such a link as 'summary-descendant', and since 3.20.0 addDependency() throws for it (along with a self-link or a cycle). Before 3.20.0 addDependency() ran neither this check nor the cycle check. Links given in the data (dependency on a task) are not checked.

Show a vertical crosshair line that follows the cursor across the timeline, with a label displaying the precise date or time at the pointer position.

Available Options:

• false (default)
• true

Color of the crosshair line and label background. Theme-aware.

Custom formatter for the crosshair label text. Receives the date under the cursor and the current sub-tier of the timeline header ('minute' | 'hour' | 'halfday' | 'day' | 'week' | 'month' | 'quarter' | 'year'). When omitted, the label auto-adapts to the active tier: coarse formats for week-and-above, HH:mm for halfday, hour, or minute tiers. Since 3.22.0, locale.crosshairFormat sets those patterns as strings, and the default label names the weekday in the date locale; this function wins over both.

crosshairLabelFormat(date, tier) {
  return `${tier}: ${date.toISOString()}`;
}

Show a tooltip on task-bar hover.

HTML id for the tooltip container element.

Custom function returning an HTML string for the task tooltip. Typed TooltipTemplate: (task, dateFormat, context) => string. Since 3.20.0 the third argument is a TooltipTemplateContext whose durationText is the task's duration exactly as the Duration column shows it ('45 m', '5 wd'); two-argument functions still work.

import { escapeHtml } from 'apexgantt'

tooltipTemplate(task, dateFormat, context) {
  return `
    <div>
      <div><strong>Task:</strong> ${escapeHtml(task.name)}</div>
      <div><strong>Start:</strong> ${task.startTime}</div>
      <div><strong>End:</strong> ${task.endTime}</div>
      <div><strong>Duration:</strong> ${context.durationText}</div>
      <div><strong>Progress:</strong> ${task.progress}%</div>
    </div>
  `;
}

Since 3.20.0 the default tooltip's Duration line matches the Duration column too ('45 m', '2 wd'); before, it showed calendar days.

The returned string is inserted as HTML, so escape task data with the exported escapeHtml as above. Since 3.22.0 the built-in tooltips show task names as text; a custom template is still responsible for its own escaping. 3.22.0 also adds messages (the resolved, translated messages), startText, endText and tag to the context. See Custom Tooltips.

Background color of the hover tooltip.

Border color of the hover tooltip.

Color for all text in the chart.

CSS font-family for the chart. Falls back to the page default when empty. Since 3.21.0 a value you pass wins over a --apex-gantt-font-family custom property on the container (in 3.20 the property won); leave the option out to let the property apply. Since 3.20.0 the variable also reaches bar and holiday tooltips, dependency-arrow tooltips and annotation labels that set no font of their own (before, those parts kept using this option).

CSS font-size for the chart. Since 3.21.0 a value you pass wins over a --apex-gantt-font-size custom property on the container (in 3.20 the property won); leave the option out to let the property apply. The property reaches the same parts as --apex-gantt-font-family (see fontFamily).

CSS font-weight for the chart.

Background color of annotation markers.

Border color of annotation markers.

SVG stroke-dasharray for annotation borders, e.g. [6, 3]. Used when an annotation sets no borderDashArray of its own. Drawn since 3.20.0; earlier versions accepted it but drew a solid border. The gaps of a dashed line annotation (one with no x2) are left empty, so the timeline shows through them; a range annotation keeps its fill.

Border width of annotation markers in pixels.

Default orientation of annotation label text, used when an annotation's label.orientation is not set. It turns only the label: the line or region itself runs down the task rows either way. Applied since 3.20.0; earlier versions accepted it but always drew horizontal labels.

Available Options:

• horizontal (default)
• vertical

When true, two vertical lines mark the project's earliest start and latest end across all rows. Auto-recomputes when tasks are added, removed, or rescheduled.

Available Options:

• false (default)
• true

Stroke color for the project-boundary lines. Falls back to annotationBorderColor when omitted.

Custom column definitions for the task-list panel. When omitted, the task list shows four columns: Name, Start, Duration and Progress. A columnConfig list replaces that set, so list every column you want, in the order you want it. See the Custom Columns guide.

Column identifier. Use a ColumnKey value for built-ins ('name', 'startTime', 'endTime', 'duration', 'progress', 'progressRing', 'wbs', 'predecessors', 'successors', 'assignees', 'baselineStart', 'baselineEnd', 'baselineVariance') or any other string for a custom column paired with a render function.

Header label displayed at the top of the column. For built-in keys it can be left out at runtime (the TypeScript type still asks for it), and the column falls back to its standard title (for example 'End' for endTime). Since 3.20.0 every built-in key has that fallback; before 3.20.0 only name, startTime, duration and progress did, and other built-in columns showed an empty header unless you set title.

CSS min-width for the column, e.g. '120px'. Acts as the column's preferred width when autoSizeColumns is on.

Upper bound for the auto-sized column width, e.g. '240px'. Caps how wide the column grows to fit content so one long value can't dominate the panel. Ignored when autoSizeColumns is off. Default '320px'.

CSS flex-grow factor for the column.

Whether the column is visible. Defaults to true.

Whether this column can be resized by dragging the handle at its header's trailing edge. Requires the resizableColumns option. Set false to lock a single column at its auto/configured width. Default true.

Custom cell renderer. Required for custom columns; ignored for built-in columns. Receives a context object (task, options, rowIndex, isSummary, isMilestone) and the cell element. Return an HTML string to set innerHTML, return void if you mounted DOM yourself, or return a cleanup function () => void that the library will invoke on row eviction, full re-render, and destroy(): required for framework adapters (React.createRoot().unmount(), Vue.app.unmount(), etc.).

Extracts the underlying value of the cell from the task. Used by sorting, filtering, and SVG export. Optional for built-in columns; for a custom column it is what makes the column sortable and filterable.

Whether the column participates in sorting (header click plus the sortBy option and gantt.sort()). Defaults to true for built-in value columns, false for the Wbs column, and true for a custom column only when an accessor or comparator is supplied.

Custom sort comparator for the column. Takes precedence over accessor-based comparison. Receives two tasks and returns a negative, zero, or positive number for ascending order; the active sort direction is applied on top. Stable: equal results fall back to natural (input) order.

Custom controls rendered in the toolbar alongside the built-in zoom and export buttons. Each item can be a ToolbarButton, ToolbarSelect, or ToolbarSeparator. Use position: 'left' to insert before the built-in controls (default is 'right').

Since 3.20.0 a 'select' item keeps its chosen value when the toolbar re-renders (before 3.20.0 it reset to the placeholder), and accepts an optional value for its initial selection.

Which control to render: 'button', 'select' or 'separator'. This decides which of the remaining keys apply.

Text label. On a 'button' it is the button text; on a 'select' it is rendered before the <select> element.

SVG string rendered as the button icon. Buttons only.

Tooltip shown on hover, set as the title attribute. Buttons only.

Where to insert the item relative to the built-in zoom and view controls. Defaults to 'right'.

Static disabled flag, or a function re-evaluated on every selection change. Buttons only.

disabled: ({ selectedTasks }) => selectedTasks.length === 0

When true, the button is disabled whenever the selection is empty. Equivalent to disabled: ({ selectedTasks }) => selectedTasks.length === 0, and more ergonomic for that common case. Defaults to false. Buttons only.

When true, the button label gains a selection count badge, for example Send (3). Only meaningful when label is also set. Defaults to false. Buttons only.

Called with the toolbar context when the button is clicked. Required on a 'button'.

Placeholder option rendered when no value is chosen. Selects only.

List of options shown in the dropdown. Required on a 'select'.

Value passed to onChange when this option is chosen.

Text shown for this option in the dropdown.

Initially selected option value of a 'select'. Once the user picks an option, that choice is kept across re-renders; pass a new item object (for example through update({toolbarItems})) to set the value again. Ignored when it matches none of options. When unset, the placeholder is shown, or the first option when there is no placeholder.

Called with the new value and the toolbar context when the selection changes. Required on a 'select'.

aria-label for the task-list table, used by screen readers.

Localization, date-locale, and text-direction options. Defaults to { direction: 'ltr' }, which reproduces the pre-localization output. See the Localization and RTL guide for worked examples.

Since 3.22.0. A locale pack: one plain-data object, safe to keep as JSON, that sets a whole language at once (messages, date names, header word order, read-only date format, week start and fiscal year start). It is the base layer under every other locale field: each explicit locale.* field wins over the pack's value (messages key by key, timelineHeaderFormat row by row), and calendar.weekStart and calendar.fiscalYearStartMonth win over the pack's. A pack never turns working days on. Object only: a string logs one warning and is ignored. update({ locale: { pack: undefined } }) returns the chart to English.

import { ja } from 'apexgantt/locales/ja'

const gantt = new ApexGantt(el, { series: tasks, locale: { pack: ja } })

ApexGantt ships one pack, Japanese, with status: 'draft'. See Locale packs.

BCP 47 tag of the pack's language. Used when locale.tag is not set. Required.

'draft' until a native-speaker reviewer signs the wording off, then 'reviewed'. Required.

Text direction of the language. locale.direction wins when you set it. Defaults to 'ltr'.

The pack's strings, in the same shape as locale.messages, which wins key by key.

The pack's date names and formats, in the same shape as locale.dateLocale, which wins over it.

Locale identifier, as for locale.dateLocale.name.

Full weekday names, Sunday first.

Short weekday names, Sunday first.

Minimal weekday names, Sunday first.

Full month names, January first.

Short month names, January first.

First day of the week in the date locale. pack.weekStart and calendar.weekStart win over it.

Week-of-year rule, as for locale.dateLocale.yearStart.

Named date formats (L, LL, LT and the rest), as for locale.dateLocale.formats.

Relative-time templates, as for locale.dateLocale.relativeTime.

AM/PM names: a function, or a JSON-safe [am, pm] pair.

Ordinal form of a number: a function, or a template string such as '{n}日'.

The pack's timeline header labels, in the same shape as locale.timelineHeaderFormat, which wins tier by tier and row by row.

Pattern for read-only dates when inputDateFormat has no time tokens. locale.displayDateFormat wins.

Pattern for read-only dates when inputDateFormat has time tokens. locale.displayDateFormat wins.

The pack's crosshair label patterns. locale.crosshairFormat and the crosshairLabelFormat function win.

Crosshair pattern on day-and-coarser tiers.

Crosshair pattern on halfday, hour and minute tiers.

First day of the week, 0 to 6. calendar.weekStart wins. Never turns working days on.

First month of the fiscal year, 1 to 12. calendar.fiscalYearStartMonth wins. Never turns working days on.

Since 3.22.0. BCP 47 language tag such as 'ja' or 'ja-JP', else the pack's tag. When one resolves it is set as the chart root's lang, and it sets the plural rules and number formatting of message templates and the collation of text sorting and grouping. It also turns the progress fields (task form and inline editor) into text fields with a decimal keyboard, so a full-width IME value such as ５０ is read as 50. A malformed tag ('ja_JP' for 'ja-JP') is ignored as if unset. Without a tag or a pack the root's lang is never touched.

Since 3.22.0. dayjs pattern for read-only dates: the task list Start, End, Baseline Start and Baseline End columns and the bar, milestone and baseline tooltips, formatted in the date locale. Editors keep inputDateFormat, and stored dates are unchanged. Unset, the pack's displayDateTimeFormat (when inputDateFormat has time tokens) or displayDateFormat applies, else inputDateFormat as before.

Since 3.22.0. Patterns for the default crosshair label, as strings, so they work from JSON and Blazor. Each wins over the pack's; the crosshairLabelFormat function wins over both.

dayjs pattern on day-and-coarser tiers. Defaults to 'ddd MM/DD/YYYY'.

dayjs pattern on halfday, hour and minute tiers. Defaults to 'MM/DD HH:mm'.

Text and layout direction.

Available Options:

• ltr (default): left-to-right
• rtl: mirrors the timeline horizontally (time flows right-to-left, the task list moves to the right) and sets dir="rtl" on the container
• auto: defers to the document or element's inherited direction

Since 3.22.0, when it is not set, locale.pack's dir applies.

dayjs-compatible locale object for the month, weekday and AM/PM names in the timeline header, the dates in bar aria-labels and the weekday in the default crosshair label. Dates shown with inputDateFormat (task list, tooltips, task form) keep that format unless locale.displayDateFormat is set. Import one from dayjs/locale/* (e.g. import localeFr from 'dayjs/locale/fr') and pass it here. ApexGantt registers it on its own bundled dayjs instance, so the host does not need to import dayjs locales. Wins over locale.pack's dateLocale.

Since 3.22.0 its week start also sets where week cells start (Monday for de, fr, ru and en-gb), unless calendar.weekStart is set, and its name is set as the lang of the timeline header rows.

Locale identifier, e.g. 'fr' or 'en'.

Full weekday names, Sunday first.

Abbreviated weekday names, Sunday first.

Minimal weekday names, Sunday first.

Full month names, January first.

Abbreviated month names, January first.

Index of the first day of the week, where 0 is Sunday. Since 3.22.0 week cells in the timeline header start on it unless calendar.weekStart is set; before, they always ran Sunday to Saturday.

Week-of-year calculation rule: the day of January that the first week of the year must contain.

Named date-format tokens keyed by dayjs format name (e.g. LT, LL).

Templates for relative-time strings, keyed by dayjs unit (e.g. future, past, dd).

Function returning the AM/PM string for a given hour, minute, and lowercase flag. Since 3.22.0 it may also be a plain [am, pm] pair (['午前', '午後']), which is JSON-safe.

Function returning the ordinal form of a number, e.g. 1 to 1st. Since 3.22.0 it may also be a '{n}日' template string.

Overrides for the Gantt's generated strings: the toolbar, context menu, task form and validation, the bar and baseline tooltips, column titles, durations, the add-task row, the export file name, filter operators and every aria-label. Accepts a partial set (GanttMessagesInput); unset keys keep the pack's text, else their English defaults, exported as DEFAULT_GANTT_MESSAGES. Wins over locale.pack's messages key by key.

Plain labels are strings. The seven keys that embed runtime data (editTaskTitle, groupCountLabel, filterOperatorLabel, summaryAriaLabel, barAriaLabel, barAriaValueText, progressAriaLabel) take a function, and since 3.22.0 also a template string such as 'Edit: {name}', with {n, number} and {n, plural, one {...} other {...}} formatted in locale.tag. 3.22.0 added 72 keys, so 124 keys can be set in all. See Overriding UI strings for the keys and their defaults.

Since 3.22.0. Timeline header labels per tier (minute, hour, halfday, day, week, month, quarter, year) and row (top, sub), in place of the built-in labels. Rows left unset keep the built-in labels. Each row takes a dayjs pattern string, an array of { minWidth?, format } candidates (the widest that fits the cell is used), or a function (date, ctx) => string. Patterns also take {end:PATTERN} (the cell's last instant), {fy} and {fq} (the fiscal year and quarter, see calendar.fiscalYearStartMonth). Output is HTML-escaped. Merged over the pack's timelineHeaderFormat row by row.

locale: {
  timelineHeaderFormat: {
    month: { top: 'MMMM YYYY' },
    week: { sub: 'M/D-{end:M/D}' },
    quarter: { sub: 'FY{fy} Q{fq}' }
  }
}

See Timeline header formats.

Field-mapping config to parse non-standard task shapes without manual data transformation. Each entry is a dot-notation path into the raw row, or { key, transform } when the value needs converting.

parsing: {
  id: 'task_id',
  name: 'title',
  startTime: 'start_date',
  endTime: 'end_date',
  progress: { key: 'pct_complete', transform: Number },
}

Since 3.20.0 parsing can also map showSummaryBar, baseline, segments, assignees and barTextColor.

A row needs an id and a name; a row without either is skipped with a warning. Since 3.20.0 a row with no start date is kept when it is the parent of a dated row (directly or further down), so a parent row can leave its dates to its children. Any other row with no start date (an unscheduled backlog item, a row with only an end date, null dates) is skipped with the console warning DataParser: Skipping item at index N: it has no start date and no dated child rows. A row whose parent id is not found is shown at the root with a console warning. Before 3.20.0 every row with no start date was skipped, and so was a row whose parent was not found.

Path to the unique task identifier in the raw data object.

Dot-notation path to the unique task identifier in the raw data object.

Coerce or rename the raw unique task identifier before ApexGantt reads it. Receives the value found at key and returns the parsed value.

Path to the task display name in the raw data object.

Dot-notation path to the task display name in the raw data object.

Coerce or rename the raw task display name before ApexGantt reads it. Receives the value found at key and returns the parsed value.

Path to the task start date in the raw data object.

Dot-notation path to the task start date in the raw data object.

Coerce or rename the raw task start date before ApexGantt reads it. Receives the value found at key and returns the parsed value.

Path to the task end date in the raw data object.

Dot-notation path to the task end date in the raw data object.

Coerce or rename the raw task end date before ApexGantt reads it. Receives the value found at key and returns the parsed value.

Path to the task progress value in the raw data object.

Dot-notation path to the task progress value in the raw data object.

Coerce or rename the raw task progress value before ApexGantt reads it. Receives the value found at key and returns the parsed value.

Path to the task type ('task' or 'milestone') in the raw data object.

Dot-notation path to the task type ('task' or 'milestone') in the raw data object.

Coerce or rename the raw task type ('task' or 'milestone') before ApexGantt reads it. Receives the value found at key and returns the parsed value.

Path to the parent task ID in the raw data object.

Dot-notation path to the parent task ID in the raw data object.

Coerce or rename the raw parent task ID before ApexGantt reads it. Receives the value found at key and returns the parsed value.

Path to the dependency field in the raw data object.

Dot-notation path to the dependency field in the raw data object.

Coerce or rename the raw dependency field before ApexGantt reads it. Receives the value found at key and returns the parsed value.

Path to a per-task bar color override in the raw data object.

Dot-notation path to the per-task bar color override in the raw data object.

Coerce or rename the raw per-task bar color override before ApexGantt reads it. Receives the value found at key and returns the parsed value.

Path to the per-task bar text color override in the raw data object.

Dot-notation path to the per-task bar text color override in the raw data object.

Coerce or rename the raw per-task bar text color override before ApexGantt reads it. Receives the value found at key and returns the parsed value.

Path to a per-task row background color override in the raw data object.

Dot-notation path to the per-task row background color override in the raw data object.

Coerce or rename the raw per-task row background color override before ApexGantt reads it. Receives the value found at key and returns the parsed value.

Path to the collapsed state in the raw data object.

Dot-notation path to the collapsed state in the raw data object.

Coerce or rename the raw collapsed state before ApexGantt reads it. Receives the value found at key and returns the parsed value.

Path to the per-task summary bar flag (showSummaryBar, a boolean; false draws a parent as a normal bar) in the raw data object.

Dot-notation path to the per-task summary bar flag (showSummaryBar, a boolean; false draws a parent as a normal bar) in the raw data object.

Coerce or rename the raw per-task summary bar flag (showSummaryBar, a boolean; false draws a parent as a normal bar) before ApexGantt reads it. Receives the value found at key and returns the parsed value.

Path to the baseline (a {start, end} object of planned dates) in the raw data object.

Dot-notation path to the baseline (a {start, end} object of planned dates) in the raw data object.

Coerce or rename the raw baseline (a {start, end} object of planned dates) before ApexGantt reads it. Receives the value found at key and returns the parsed value.

Path to the segments (an array of {start, end} worked spans) in the raw data object.

Dot-notation path to the segments (an array of {start, end} worked spans) in the raw data object.

Coerce or rename the raw segments (an array of {start, end} worked spans) before ApexGantt reads it. Receives the value found at key and returns the parsed value.

Path to the assignees (an array of Assignee objects) in the raw data object.

Dot-notation path to the assignees (an array of Assignee objects) in the raw data object.

Coerce or rename the raw assignees (an array of Assignee objects) before ApexGantt reads it. Receives the value found at key and returns the parsed value.

Task data array. Each item must satisfy TaskInput, or use parsing to map custom field names. Dates are parsed with inputDateFormat ('MM-DD-YYYY' by default, as in this example).

Since 3.20.0 a task can also set barTextColor, the colour of the label drawn inside its bar, overriding the global barTextColor.

series: [
  {
    id: 'task-1',
    name: 'Design Phase',
    startTime: '01-01-2026',
    endTime: '01-15-2026',
    progress: 65,
  },
  {
    id: 'task-2',
    name: 'Development',
    startTime: '01-10-2026',
    endTime: '02-01-2026',
    parentId: 'task-1',
    progress: 30,
    dependency: 'task-1',
  },
]

Unique identifier for the task. Must be stable across renders.

Display name shown in the task list column and task bar.

Task start date string. Parsed using inputDateFormat. Required on every row except a parent, whose summary bar takes its dates from its children; optional in the TypeScript types since 3.20.0. A task with no startTime and no children throws Task "<id>" has no startTime and no children. Provide dates or add child tasks. (since 3.20.0; this also covers a task with only an endTime and a type: 'milestone' task with no start, which threw a different message before).

Task end date string. Parsed using inputDateFormat. Since 3.20.0, when it is omitted and type is not set, a task without children renders as a milestone on startTime, and a parent stays a 'task' drawn as a summary bar spanning its children; an explicit type: 'task' with no endTime still throws. Before 3.20.0 a task without endTime threw unless it had type: 'milestone'. Since 3.20.0 a parent with only an endTime is also drawn as a summary bar over its children (it used to throw Task must have an id, start, and end date).

Completion percentage (0-100). Renders a filled progress portion inside the task bar.

Visual type of the task. Since 3.20.0 the types accept the plain strings as well as the TaskType enum, so type: 'milestone' compiles in TypeScript.

Available Options:

• task: renders a bar (default)
• milestone: renders a diamond marker

A parent row is drawn as a summary bar through showSummaryBar, not through type; there is no 'summary' type.

ID of the parent task. Nested tasks are rendered as children in the task list. 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.

Dependency on another task. Accepts either a plain task ID string (treated as Finish-to-Start with 0 lag) or a full TaskDependency object for typed dependency with lag/lead support.

// Simple string dependency
dependency: 'task-2'

// Full dependency object
dependency: { taskId: 'task-2', type: 'FS', lag: 2 }

ID of the task this task depends on.

Dependency type. Defaults to 'FS'.

Available Options:

• FS: finish to start (default)
• SS: start to start
• FF: finish to finish
• SF: start to finish

Lag (positive) or lead (negative) in days between the linked ends. Defaults to 0. It counts working days when a calendar is set and calendar days otherwise. Lag feeds the critical path and the arrow tooltip only: dependencies never move tasks, so a lag does not shift the successor's dates.

Deprecated, has no effect. It is accepted for compatibility but never read, in any version. Lag counts working days when a calendar is set and calendar days otherwise, whatever this field says.

Override the task bar fill color for this specific task.

Override the colour of the label drawn inside this task's bar, instead of the global barTextColor. Since 3.20.0.

Override the row background color for this specific task row.

Baseline (planned) dates for comparison against actual dates. Rendered as a thin bar below the actual task bar when baseline.enabled is true.

Planned (baseline) start date of the task.

Planned (baseline) end date of the task.

Whether this task's child tasks are collapsed (hidden) in the task list. To open or close a parent at runtime, use expandTask() / collapseTask() (3.20.0+), which do not touch undo history. Since 3.20.0 updateTask(id, { collapsed }) also re-renders so the rows appear or disappear immediately.

When true (the default), a task with children renders as a summary (group) bar whose date range is automatically computed from the earliest start and latest end of all its descendants: the task's own startTime / endTime are ignored. Drag, resize, and progress edits are disabled on summary bars. Set to false to opt the parent out of the auto-derived summary bar and render it as a normal task bar instead.

People (or teams) assigned to this task. Consumed by the built-in renderers.avatars column renderer; ignored unless an avatar-style column is configured via columnConfig. Each Assignee carries name, optional avatarUrl, optional initials, and optional fallback color.

Display name. Used as the avatar's alt text and as the source for generated initials.

Avatar image URL. When omitted, initials are rendered instead.

Initials override. Defaults to the first letters of name.

Background color for the initials fallback.

Worked spans of a split task, each { start, end } (not startTime / endTime). When two or more are provided, the task renders as separate bar pieces with gaps between them, and its startTime / endTime are derived from the segments (first start to last end). Omit, or provide fewer than two, for a normal contiguous task. Since 3.20.0 a single segment is stored as a plain task: it sets startTime and endTime, and the segments field is not kept (so updateTask(id, { segments: [one] }) un-splits a task). Split a task at runtime via gantt.splitTask(). See the Split Tasks guide.

Start date of this worked span.

End date of this worked span.

Array of annotation objects to overlay on the timeline.

annotations: [
  {
    x1: '01-15-2026',
    x2: '01-20-2026',
    label: { text: 'Sprint Review' },
  },
  {
    x1: '02-01-2026',
    label: { text: 'Deadline' },
  },
]

Start date of the annotation, parsed with inputDateFormat.

End date of annotation. If present, draws a rect from x1 to x2. If null or omitted, only draws a line on x1.

Background color of this annotation. Overrides the global annotationBgColor.

Border color of this annotation. Overrides the global annotationBorderColor.

SVG stroke-dasharray for this annotation's border, overriding annotationBorderDashArray. Drawn since 3.20.0, which also accepts an array ([6, 3]) as well as a single number; earlier versions accepted a number but drew a solid border.

Border width of this annotation in pixels.

Label configuration for the annotation.

Label text for the annotation.

Font color for the annotation label.

Font family for the annotation label.

Font size for the annotation label.

Font weight for the annotation label.

Text orientation of the annotation label. Falls back to annotationOrientation. Applied since 3.20.0; earlier versions accepted it but always drew horizontal labels.

Available Options:

• horizontal
• vertical

Working-calendar configuration. When set, weekends and holidays drive duration math, summary aggregation, and timeline stripes. Absent means every day is a working day. See the Calendar and Working Days guide.

Since 3.20.0 any calendar object you pass, even {}, turns the working calendar on with a Monday to Friday week. The exception, since 3.22.0, is a calendar that holds only weekStart and fiscalYearStartMonth: it shapes the timeline header and leaves every day a working day. Before 3.20.0 it only took effect when workingWeekdays or holidays was set. Since 3.20.0, update() rebuilds the calendar when you pass calendar or inputDateFormat, and a theme change keeps it; before 3.20.0 update() left the original calendar in place.

Weekdays that count as working days, where 0 is Sunday and 6 is Saturday. Default [1, 2, 3, 4, 5] (Mon-Fri). Since 3.20.0 numeric strings ('1') are read as numbers, and a list that names no weekday from 0 to 6 ([], [7]) logs a warning and falls back to Monday to Friday; before, it made every day non-working.

Specific non-working dates, regardless of weekday. Each entry may be a date string, a Date, or { date, label } for a tooltipped holiday. Default []. Since 3.20.0 date strings are read with inputDateFormat, like task dates, and ISO YYYY-MM-DD always works: in a DD-MM-YYYY chart '03-04-2026' is 3 April (it was read as 4 March before), and '25-12-2026' is no longer dropped.

The holiday date, as a date string or a Date. Use this object form when the holiday also needs a label; otherwise pass the date on its own.

Display label for the holiday. Passed to calendar.holidayTooltip as part of { date, label }.

Render tinted bands over non-working timeline columns. Default true. Since 3.20.0 the bands are drawn above the row backgrounds and below the bars; before 3.20.0 an opaque row background could hide them.

Optional function returning an HTML string shown when hovering a holiday stripe. Receives { date, label }. Shown on hover since 3.20.0; before 3.20.0 the stripe sat under the rows and the tooltip did not appear.

Where a drag or resize lands when it hits a non-working day.

Available Options:

• next (default): snap forward to the next working day
• previous: snap backward to the previous working day
• allow: permit non-working start/end dates

Since 3.22.0. First day of the week, 0 (Sunday) to 6 (Saturday). Week cells in the timeline header start on it, and week numbers (w, the built-in Wk labels) follow it. Unset, the pack's weekStart applies, then the locale.dateLocale's own week start (Monday for de, Saturday for ar), else Sunday. Anything other than a whole number from 0 to 6 logs a warning and is ignored. Set 0 to keep Sunday weeks under a Monday-week date locale.

Since 3.22.0. First month of the fiscal year, 1 (January) to 12 (December). Defaults to 1. Quarter and year cells in the timeline header start on fiscal boundaries, and the built-in labels read as fiscal periods: with 4, the year from April 2026 to March 2027 reads FY2026 (named by the year it starts in) and its first quarter #1 Apr-Jun. Month, week and day cells are unaffected. Anything other than a whole number from 1 to 12 logs a warning and January is used.

Undo/redo history configuration. Every mutating call (drag, resize, inline/dialog edit, add, delete, move, dependency change) is recorded unless disabled. Since 3.20.0, update({ series }) replaces the data and clears the history. See the Undo and Redo guide.

When false, no commands are recorded and undo() / redo() are no-ops. Default true.

Maximum number of undo entries retained; older entries drop off the bottom (FIFO). Default 100.

Veto hook called immediately before a task is inserted, through addTask() or the built-in add affordances (toolbar, context menu, add-task row, drawing a task). Receives { input, parentId }, where input is the TaskInput about to be added and parentId is the parent it will land under: the addTask() option, else input.parentId, and undefined for a root task (including an id that matches no task). Before 3.20.0 input.parentId was not reported. Return false to cancel the insertion. Hooks are synchronous: a returned Promise is not awaited and does not veto.

Veto hook called before a task update commits. Receives one object, { task, updates }: the task as it is now and the partial update about to be applied. Return false to reject the change: nothing is stored, no update event fires, nothing is recorded in undo history, and the bar is repainted from the data. Hooks are synchronous: a returned Promise is not a veto.

Since 3.20.0 it runs for every edit path: drag, resize, progress drag, dialog save, inline edit, keyboard move or resize, and updateTask(). Before 3.20.0 it ran only for updateTask() and inline edits. See the Inline Editing guide.

During a parent drag or keyboard move it is asked about the parent and each child that moves with it. Since 3.20.0 vetoing one child keeps only that child in place and the later siblings are still asked; vetoing the parent skips all its children.

Veto hook called before a task is re-parented via moveTask() or an indent/outdent. Receives { task, oldParentId, newParentId } (a parent id is undefined at the root). Return false to cancel the move. Synchronous.

Veto hook called before a task is removed via deleteTask(). Receives { task, descendantIds, cascade }. Return false to cancel the deletion. Synchronous.

Veto hook called before a dependency is added or removed (interactively or via addDependency() / removeDependency()). Receives { change, fromId, toId, type, lag }, where change is 'add' or 'remove'. Return false to reject the change. Synchronous.