Theming and Customization

ApexGantt ships with built-in light and dark themes. Every color token is individually overridable, bar labels support custom HTML renderers, and the entire timeline can be mirrored for right-to-left languages.


Built-in themes

The theme option accepts 'light' (default) or 'dark'. The dark preset adjusts bar colors, backgrounds, and borders to suit dark surfaces without requiring any manual color overrides. Since 3.21.0 it also takes the name of a theme registered on the registry the Apex products share (registerTheme from apex-commons, or ApexCharts.registerTheme); see Registered themes.

// Initialize with dark theme
const gantt = new ApexGantt(document.querySelector('#chart'), {
  series: tasks,
  theme: 'dark'
})

You can switch the theme at runtime using update(). The chart re-renders immediately with no page reload required. Keep track of the current theme in your own code: the chart's options are internal.

// Toggle between themes
let theme = 'light'

document.querySelector('#toggle-theme').addEventListener('click', () => {
  theme = theme === 'dark' ? 'light' : 'dark'
  gantt.update({ theme })
})

Since 3.20.0 a theme change resets only the colours the theme owns to the new theme's values, even ones you set yourself: annotationBgColor, annotationBorderColor, arrowColor, backgroundColor, barBackgroundColor, barTextColor, borderColor, cellBorderColor, criticalArrowColor, criticalBarColor, crosshairColor, fontColor, headerBackground, milestoneColor, rowBackgroundColors, summaryBarColor, tooltipBGColor and tooltipBorderColor. Pass a custom colour in the same update() call to keep it. Every other option (columns, toolbar items, hooks, locale, sortBy, barLabel, dependencies, calendar, ...) carries over, and so do the task data and edits.

gantt.update({ theme: 'dark', barBackgroundColor: brandColor })

Since 3.21.0 update({ theme: undefined }) returns a chart to no theme: the light colours, or, with the Ignite UI add-on loaded, the design system's dark variant when it declares one. The theme stops counting as one you passed. Before 3.21.0 the chart kept the mode it had, so a dark chart stayed dark until it was mounted again. A framework binding such as theme: isDark ? 'dark' : undefined relies on this to go back to light.

On 3.19 and earlier a theme change rebuilt the options from the new theme's defaults and kept only a fixed list of 18 keys (data, size, zoom, row height, date format, annotations and the main editing toggles), so columns, toolbar items, hooks and locale also had to be passed again in the same call.

Registered themes

Since 3.21.0 theme also takes the name of a theme registered on the registry the Apex products share. Register it with registerTheme from apex-commons (install that package to import it), or with ApexCharts.registerTheme on a page that already loads ApexCharts:

import { registerTheme } from 'apex-commons'

registerTheme('dusk', { mode: 'dark', tokens: { accent: '#0f766e', surface: '#1c1917' } })

const gantt = new ApexGantt(el, { series: tasks, theme: 'dusk' })

The theme's tokens fill the same slots as the family --apx-* tokens (surface, fore, grid, accent and font), one rank below them and above the design system. mode: 'dark' gives every other colour the dark theme's value; without it the theme is light. A name nothing is registered under renders as 'light', and a theme registered under 'light' or 'dark' adds its tokens to that built-in theme. An update() that passes a theme of the same mode keeps the colours you set; one that changes the mode resets the theme's colours as described above.


Color customization

All color options are optional. Unset options fall back to the theme default (light or dark). Override only the tokens you need.

OptionLight defaultDark defaultWhat it controls
backgroundColor#FFFFFF#1E1E1EChart container background
rowBackgroundColors['#FFFFFF']['#1E1E1E', '#252525']Row background pattern
headerBackground#F8F9FB#2A2A2ATimeline and task-list header background
fontColor#1F2933#E0E0E0Text in the task list, headers and tooltips
borderColor#E5E7EB#3A3A3ATask-list row dividers, and toolbar, dialog and control borders
cellBorderColor#EDEFF2#3A3A3ATask table and timeline grid cell borders
barBackgroundColor#87B7FE#818CF8Default task bar fill
barTextColor#FFFFFF#FFFFFFText rendered inside task bars
summaryBarColor#94A3B8#8FBCBCSummary/parent row bar color
milestoneColor#7C3AED#A78BFAMilestone diamond color
arrowColor#94A3B8#94A3B8Dependency arrow lines
criticalBarColor#E53935#F87171Task bar on the critical path
criticalArrowColor#E53935#F87171Dependency arrows on the critical path
crosshairColor#3B82F6#818CF8Crosshair line and label
tooltipBGColor#FFFFFF#2D2D2DTooltip background
tooltipBorderColor#E5E7EB#444444Tooltip border
annotationBgColor#DBEAFE#4A2D4DRange annotation fill
annotationBorderColor#60A5FA#8B4D8FAnnotation lines and borders

The LightTheme and DarkTheme exports carry these colours (since 3.20.0; the 3.19 LightTheme still held a zebra row stripe and older border and header colours that the chart no longer drew). To start from a preset and change a few colours, spread it into the options ({ ...LightTheme, barBackgroundColor: '#22C55E', series: tasks }); the theme option itself takes 'light', 'dark' or a registered theme's name, not a preset object.

The following example applies a neutral, low-contrast palette suited to a dashboard that uses muted grays:

const gantt = new ApexGantt(document.querySelector('#chart'), {
  series: tasks,
  theme: 'light',
  backgroundColor: '#F9FAFB',
  headerBackground: '#F3F4F6',
  barBackgroundColor: '#6366F1',
  barTextColor: '#FFFFFF',
  summaryBarColor: '#A1A1AA',
  milestoneColor: '#8B5CF6',
  criticalBarColor: '#EF4444',
  arrowColor: '#CBD5E1',
  borderColor: '#E5E7EB',
  cellBorderColor: '#E5E7EB'
})

Per-task colors

Task bar color

Set barBackgroundColor directly on a task object inside series to override the global bar color for that specific task. This is useful for encoding priority, status, or ownership without a separate legend. Since 3.20.0 a task can also set barTextColor for the label drawn inside its bar, which helps when a light bar colour needs dark text.

const gantt = new ApexGantt(document.querySelector('#chart'), {
  inputDateFormat: 'YYYY-MM-DD',
  series: [
    {
      id: 'design',
      name: 'Design',
      startTime: '2024-03-01',
      endTime: '2024-03-10'
      // Uses global barBackgroundColor
    },
    {
      id: 'urgent',
      name: 'Critical Fix',
      startTime: '2024-03-04',
      endTime: '2024-03-06',
      barBackgroundColor: '#FF4560'  // Red bar for this task only
    },
    {
      id: 'review',
      name: 'Review',
      startTime: '2024-03-08',
      endTime: '2024-03-12',
      barBackgroundColor: '#00E396'  // Green bar to signal approved
    }
  ]
})

Row background color

Set rowBackgroundColor on a task to highlight its entire row. This is separate from rowBackgroundColors (the alternating pattern) and takes precedence over it.

const gantt = new ApexGantt(document.querySelector('#chart'), {
  inputDateFormat: 'YYYY-MM-DD',
  series: [
    {
      id: 'phase-1',
      name: 'Phase 1',
      startTime: '2024-03-01',
      endTime: '2024-03-31',
      rowBackgroundColor: '#EEF2FF'  // Indigo tint for the entire row
    },
    {
      id: 'task-1a',
      name: 'Task 1A',
      startTime: '2024-03-01',
      endTime: '2024-03-10',
      parentId: 'phase-1'
    },
    {
      id: 'phase-2',
      name: 'Phase 2',
      startTime: '2024-04-01',
      endTime: '2024-04-30',
      rowBackgroundColor: '#F0FDF4'  // Green tint for Phase 2
    }
  ]
})

Row alternating background

rowBackgroundColors accepts an array of color strings that cycle across rows from top to bottom. The default is a single-color array (['#FFFFFF']), which produces a uniform background. Passing two colors produces a classic zebra stripe.

const gantt = new ApexGantt(document.querySelector('#chart'), {
  series: tasks,
  rowBackgroundColors: ['#FFFFFF', '#F8F9FA']
})

You can pass more than two colors. The pattern repeats from the beginning once all colors are used:

rowBackgroundColors: ['#FFFFFF', '#F5F3FF', '#F0FDF4']
// Row 1 = white, Row 2 = lavender, Row 3 = green, Row 4 = white again, ...

Note that a per-task rowBackgroundColor overrides the alternating pattern for that specific row.


Bar label position and content

Position

The barLabel.position option controls where the label appears relative to the task bar. The four accepted values are:

  • 'inside': label renders inside the bar. The bar must be wide enough to display it.
  • 'left': label renders to the left of the bar.
  • 'right' (default): label renders to the right of the bar.
  • 'auto': the chart picks 'inside' when the bar is wide enough, and 'right' otherwise.
const gantt = new ApexGantt(document.querySelector('#chart'), {
  series: tasks,
  barLabel: {
    position: 'auto',
    field: 'name'
  }
})

Field

barLabel.field sets which property from the task object is used as the label text. The default is 'name'. You can point it at any property present on your task objects, for example 'assignee' or 'progress'.

barLabel: {
  position: 'right',
  field: 'name'
}

Custom render function

For full control over what appears in the label, supply a render function. It receives the resolved task object and must return an HTML string, an HTMLElement, or null/undefined (which falls back to the field value).

This approach lets you inject icons, progress indicators, or any markup into the label without modifying task data.

const gantt = new ApexGantt(document.querySelector('#chart'), {
  series: tasks,
  barLabel: {
    position: 'right',
    render: (task) => {
      if (task.progress == null) return null

      const color = task.progress >= 100 ? '#10B981' : '#6366F1'
      return `<span style="display:flex;gap:6px;align-items:center;font-size:12px">
        <strong>${task.name}</strong>
        <span style="color:${color};opacity:0.85">${task.progress}%</span>
      </span>`
    }
  }
})

Return null or undefined from render to let the chart fall back to the field value. This makes conditional rendering straightforward: enhance milestone tasks with an icon but leave regular tasks as plain text.


Typography

The following options control the font used across the entire chart (bars, headers, the task table, and tooltips). They accept any valid CSS value. Since 3.21.0 a fontFamily or fontSize you pass wins over the --apex-gantt-font-family and --apex-gantt-font-size custom properties on the container; leave the option out to let the property apply (see below).

const gantt = new ApexGantt(document.querySelector('#chart'), {
  series: tasks,
  fontFamily: 'Inter, sans-serif',
  fontSize: '13px',
  fontWeight: '400',
  fontColor: '#374151'
})
OptionDefaultDescription
fontFamily'system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif'Font stack for all chart text
fontSize'14px'Base font size
fontWeight'400'Base font weight
fontColor'#1F2933' (dark theme '#E0E0E0')Default text color (task table, headers, tooltips)

Bar text color is controlled separately by barTextColor.


Row height and bar border radius

Row height

rowHeight sets the height of each task row in pixels. The default is 40. Increasing it gives more breathing room between bars, which helps when bars carry labels or progress indicators.

const gantt = new ApexGantt(document.querySelector('#chart'), {
  series: tasks,
  rowHeight: 48
})

Bar border radius

barBorderRadius accepts any CSS border-radius value. The default is '5px'. Set it to '0' for sharp rectangular bars or '12px' for a pill-like appearance.

const gantt = new ApexGantt(document.querySelector('#chart'), {
  series: tasks,
  barBorderRadius: '8px'
})

RTL support

Setting locale.direction to 'rtl' mirrors the entire timeline axis so dates progress from right to left. The task table moves to the right side of the chart. This is intended for Arabic, Hebrew, and Persian project plans where right-to-left reading order is expected.

const gantt = new ApexGantt(document.querySelector('#chart'), {
  series: tasks,
  locale: {
    direction: 'rtl'
  }
})

The default is 'ltr'. Switching direction at runtime with update() is supported:

gantt.update({ locale: { direction: 'rtl' } })

Since 3.20.0 a right-to-left chart opens at the start of the timeline, scrollToTask() and setState({ scroll }) work, and bars stay in the right place after zooming. Earlier versions could open scrolled to the far end and misplace bars after a zoom.


Setting --apex-gantt-* on the container

You can set these custom properties inline on the host element, or from a stylesheet rule that targets it, and the chart reads them when it renders:

PropertySame value as
--apex-gantt-bar-fillbarBackgroundColor
--apex-gantt-dependency-linearrowColor
--apex-gantt-background-colorbackgroundColor
--apex-gantt-header-bgheaderBackground
--apex-gantt-grid-linecellBorderColor
--apex-gantt-font-colorfontColor
--apex-gantt-row-bg-evenrowBackgroundColors[0]
--apex-gantt-row-bg-oddrowBackgroundColors[1]
--apex-gantt-font-familyfontFamily
--apex-gantt-font-sizefontSize
<div id="chart" style="--apex-gantt-bar-fill: #4f46e5; --apex-gantt-grid-line: #e5e7eb"></div>

Since 3.21.0 an option you pass wins over the matching property, even when you pass the option's default value: barBackgroundColor: '#87B7FE' beats --apex-gantt-bar-fill. A property set here wins over the family --apx-* tokens, a registered theme, the design system and the built-in default, so it is the way to restyle a chart whose options leave the colour unset. A per-task barBackgroundColor wins over all of them for that task. In 3.20 and earlier the property won over the option.

Since 3.20.0 --apex-gantt-bar-fill (falling back to --apx-accent) recolours the task bars and --apex-gantt-dependency-line recolours the dependency arrows. Before 3.20.0 both reached only the dialog buttons and hover states, while bars and arrows kept painting from the options.

Since 3.20.0 --apex-gantt-font-family and --apex-gantt-font-size reach the chart text, the bar and holiday tooltips, the dependency-arrow tooltips, and annotation labels that set no font of their own. Before, those tooltips and labels used the fontFamily and fontSize options even when the variables were set.

The values are resolved when the chart renders, not live. After changing one (for example when your app switches its own theme), call gantt.update({}) to repaint. On 3.19 and earlier, update() also rebuilt the tasks from the original series, so edits made in the chart were lost; from 3.20.0 they are kept.

Fixed in 3.18.0: every render used to wipe ten of these properties inline before reading, while the chart only ever wrote two. An inline --apex-gantt-bar-fill or --apex-gantt-grid-line you set on the container was therefore erased silently on the next render. Only the two row-background properties the chart actually owns are cleared now, and only while the value sitting there is still the one it wrote.

The same release stopped the row painter reading --apex-gantt-row-bg-* back off the element after the style manager had just written them. The chart's own value was indistinguishable from one you set, which was harmless while they matched but would have frozen the row colours against any later theme change.

Family root tokens

Declare the --apx-* tokens once on :root and ApexCharts-family visuals on the page read them from there. How far a product follows them varies, so check the token against the product: measured on apexsankey 1.12.2, a sankey diagram takes --apx-fore for label fill and --apx-grid for node strokes, and ignores --apx-surface and --apx-series-N. ApexGrid sits outside this layer altogether: apex-grid 3.5.0 contains no --apx-* at all and themes through its own --ag-* variables.

ApexGantt maps them like this:

TokenApexGantt colour
--apx-surfacebackgroundColor, headerBackground and the base row background
--apx-forefontColor
--apx-gridcellBorderColor and arrowColor
--apx-accentbarBackgroundColor (reaches the bars since 3.20.0)

ApexGantt does not read --apx-series-N.

:root {
  --apx-accent: #4f46e5;   /* primary accent */
  --apx-fore: #1f2937;     /* text and labels */
  --apx-grid: #e5e7eb;     /* gridlines, borders and separators */
  --apx-surface: #ffffff;  /* background surface */
  /* ordered palette for multi-series visuals */
  --apx-series-1: #4f46e5;
  --apx-series-2: #06b6d4;
}

ApexGantt reads them when it renders, not live. After the tokens change (an OS light/dark flip, or a host app swapping its design system), call gantt.update({}) so the chart picks up the new values.

They resolve below anything you set explicitly. A chart already themed through its own options, or through the --apex-gantt-* variables, is untouched. Since 3.21.0 the order for ApexGantt, highest first, is:

  1. an option you pass,
  2. the --apex-gantt-* properties on the container,
  3. these family --apx-* tokens,
  4. a registered theme named in theme,
  5. the page's design system (Ignite UI, with the add-on loaded),
  6. the built-in default.

An option counts as passed when it is in the options object you gave the chart, even at its default value; leave it out (or pass undefined to update()) to let the layers below fill it. Per-task colours win over all of them for that task. In 3.20 the --apex-gantt-* properties ranked above the options, and an option counted as set only when its value differed from the built-in default.

The point is that these are not this library's variables. They are the family's, so a design system declares its palette once rather than once per product.

From ApexGantt 3.21.0, an Ignite UI theme on the page can supply the chart's colors, font and dark mode too, through an add-on that needs no extra licence key, ranked below these tokens and any named or registered theme. See Using with Ignite UI, which also gives the full resolution order for that release.

Custom CSS injection

canvasStyle accepts a raw CSS string that is applied directly to the root chart container element. Use it for overrides that have no dedicated option: custom scrollbar styling, pointer cursors on hover, or additional box-shadow effects.

const gantt = new ApexGantt(document.querySelector('#chart'), {
  series: tasks,
  canvasStyle: `
    border: 1px solid #E5E7EB;
    border-radius: 8px;
    box-shadow: 0 1px 3px 0 rgba(0,0,0,0.1);
    font-feature-settings: 'tnum';
  `
})

A common use case is customizing the scrollbar in Chromium-based browsers so it blends with your chart's color scheme:

canvasStyle: `
  border: 1px solid #CACED0;
  box-sizing: border-box;
  scrollbar-width: thin;
  scrollbar-color: #CBD5E1 transparent;
`

Because canvasStyle is a raw string injection, it bypasses the options type system. Prefer dedicated options (like backgroundColor or borderColor) when they cover your use case, and fall back to canvasStyle only for properties that have no dedicated option.