Theming and Customization

ApexTree ships with built-in light and dark themes and exposes every color, border, shadow, and font as an option. The main colors, the font and the built-in card also read --apex-tree-* CSS variables, so a stylesheet can theme a tree without touching its options.

Built-in themes

The theme option selects a preset:

ValueDescription
'light' (default)Soft-neutral palette suitable for most pages
'dark'Dark palette with slate backgrounds and muted edges. Its node and edge colors rank as a named theme: an option you pass, an --apex-tree-* variable and an --apx-* token all beat them
'custom'Same as 'light': the tree injects no variables, so the ones you set stay in charge. Kept for compatibility
Any other nameA theme registered with registerTheme from apex-commons; behaves like 'custom' plus that theme's tokens

Left unset, theme follows an Ignite UI theme on the page that declares a dark variant, when the Ignite UI add-on is loaded. Naming any theme, 'light' included, pins it.

const tree = new ApexTree(document.getElementById('chart'), {
  theme: 'dark',
})
tree.render(data)

Node colors and borders

OptionTypeDefaultDescription
nodeBGColorstring'#FFFFFF'Node background
nodeBGColorHoverstring'#FFFFFF'Node background on hover
borderColorstring'#BCBCBC'Border color
borderColorHoverstring'#5C6BC0'Border color on hover
borderWidthnumber1Border width in pixels
borderStylestring'solid'CSS border-style
borderRadiusstring'5px'CSS border-radius
const tree = new ApexTree(el, {
  nodeBGColor: '#F8FAFC',
  nodeBGColorHover: '#EEF2FF',
  borderColor: '#CBD5E1',
  borderColorHover: '#6366F1',
  borderRadius: '10px',
  borderWidth: 1,
})

Shadows and hover lift

OptionTypeDescription
nodeShadowstringCSS box-shadow in the default state; empty string disables it
nodeShadowHoverstringbox-shadow on hover (paired with a subtle lift)
const tree = new ApexTree(el, {
  nodeShadow: '0 1px 3px rgba(16,24,40,0.1)',
  nodeShadowHover: '0 4px 8px rgba(16,24,40,0.15)',
})

highlightOnHover (on by default) highlights the hovered node and its connecting edges. Set it to false to disable hover emphasis entirely.

Fonts

OptionTypeDefaultDescription
fontColorstring'#000000'Node text color
fontFamilystring''Font family; empty falls back to the page default
fontSizestring'14px'Font size
fontWeightstring'400'Font weight
const tree = new ApexTree(el, {
  fontColor: '#0F172A',
  fontFamily: 'Inter, sans-serif',
  fontSize: '14px',
  fontWeight: '500',
})

Edge colors

Edge appearance is covered in Directions and Layouts. In short: edgeColor, edgeColorHover, edgeWidth, and edgeColorMode: 'node' (to match edges to their child node's border color).

CSS variables

Set these on the container or any ancestor. This is the cleanest way to tie a tree to a design system or to a dark-mode toggle driven by your app, since a class or a prefers-color-scheme query can switch them:

.org-chart {
  --apex-tree-node-bg: #1e293b;
  --apex-tree-node-border: #334155;
  --apex-tree-edge-stroke: #475569;
  --apex-tree-font-color: #e2e8f0;
}
// leave out nodeBGColor, borderColor, edgeColor and fontColor:
// an option you pass beats the variable
const tree = new ApexTree(document.querySelector('.org-chart'), {
  nodeWidth: 160,
  nodeHeight: 56,
})
tree.render(data)
VariableSets
--apex-tree-node-bgnodeBGColor
--apex-tree-node-bg-hovernodeBGColorHover
--apex-tree-node-borderborderColor
--apex-tree-node-border-hoverborderColorHover
--apex-tree-node-border-radiusborderRadius
--apex-tree-edge-strokeedgeColor
--apex-tree-edge-stroke-hoveredgeColorHover
--apex-tree-font-colorfontColor
--apex-tree-font-familyfontFamily
--apex-tree-font-sizefontSize
--apex-tree-expand-btn-bgexpandCollapseButtonBGColor
--apex-tree-expand-btn-borderexpandCollapseButtonBorderColor
--apex-tree-expand-btn-iconexpandCollapseButtonIconColor
--apex-tree-expand-btn-haloexpandCollapseButtonHaloColor
--apex-tree-badge-bgcollapseBadgeBGColor
--apex-tree-badge-colorcollapseBadgeFontColor
--apex-tree-badge-font-sizecollapseBadgeFontSize

Precedence. From 2.3.0 every styling option resolves in one order, highest first:

  1. An option you pass. It counts as passed when it is in the options you gave the constructor, even at its default value.
  2. The --apex-tree-* variable.
  3. The family --apx-* token for that role (see below).
  4. The 'dark' preset or a registered theme.
  5. An Ignite UI theme, with the Ignite UI add-on loaded.
  6. The built-in default.

Two things changed in 2.3.0. A variable used to beat an option you passed; now the option wins, so drop the option from your config if a variable should drive it. And theme: 'dark' used to write 13 node and edge variables on the container itself, which hid the same variables set on an ancestor; it no longer writes them, and its colors sit below your variables wherever you set them.

Search, breadcrumb and command palette

The DOM controls read their own variables, all with light defaults: --apex-tree-search-{bg,border,color,placeholder,count-color,match}, --apex-tree-breadcrumb-{bg,border,color,hover-bg,hover-color,current-color,separator}, --apex-tree-cmdk-{backdrop,bg,border,color,placeholder,hint,active-bg,active-color}, and --apex-tree-selection-ring for the selection outline. Under theme: 'dark' the tree declares dark values for these on the container, which beat the same variables inherited from an ancestor; 'light' and 'custom' declare none.

Card colors

From 2.3.0 the built-in org-chart card paints its secondary text, chips, hairline, progress track, links and chevron from variables, so a page restyles the card without a custom template. Each falls back to the color the card always had. With the Ignite UI add-on loaded and an Ignite UI theme on the page, an unset --apex-tree-card-* variable (other than the two badge ones) takes the matching --apx-* token, then the registered theme, then the Ignite UI theme, before that built-in color. A node's own badge.color, progress.color and accentColor still win.

VariableDefaultPaints
--apex-tree-card-secondary#475467Title, meta rows, tag text, details text
--apex-tree-card-muted#667085Subtitle, stat labels, the progress caption, the compact tier's role
--apex-tree-card-text#101828Stat values
--apex-tree-card-chip-bg#F1F5F9Tag chip background
--apex-tree-card-track#EEF2F6Progress track
--apex-tree-card-divider#EAECF0The hairline above the detail section
--apex-tree-card-chevron#98A2B3The expand chevron
--apex-tree-card-accent#5C6BC0Action links and the default progress fill
--apex-tree-card-badge-bg#EEF2FFStatus chip background when badge.color is not set
--apex-tree-card-badge-color#1E3A8AStatus chip text
--apex-tree-lod-accent#94A3B8The semantic zoom compact and dot tiers' accent when a node has no accentColor
--apex-tree-lod-dot-color#fffThe name on the dot tier's slab

exportToSvg() copies the card variables in force onto the exported file, so it keeps the page's card colors.

Changing variables after render

The tree reads its variables and tokens when it renders, not live. After a change that does not render the tree again (a class toggle, a stylesheet swap, an OS light or dark flip picked up by a media query), call refreshTokens(). It repaints at the current zoom and keeps nodes, expanded cards, selection, focus mode and the active path:

document.body.classList.toggle('dark')
tree.refreshTokens()

// follow the OS setting when your variables sit in a prefers-color-scheme query
matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => tree.refreshTokens())

See Methods.

Family root tokens

Declare the --apx-* tokens once on :root and every ApexCharts-family product on the page reads them from there. Each product maps them to its own parts; a tree reads these:

TokenTree options it fills
--apx-forefontColor
--apx-gridborderColor, edgeColor, expandCollapseButtonBorderColor
--apx-accentborderColorHover, edgeColorHover, collapseBadgeBGColor, expandCollapseButtonIconColor
--apx-surfacenodeBGColor, expandCollapseButtonBGColor
--apx-font-familyfontFamily

A tree does not read --apx-series-N. Set tokens: false to stop one tree reading the --apx-* tokens.

:root {
  --apx-accent: #4f46e5;   /* primary accent */
  --apx-fore: #1f2937;     /* text and labels */
  --apx-grid: #e5e7eb;     /* gridlines, borders and separators */
  --apx-surface: #ffffff;  /* node background */
  --apx-font-family: Inter, sans-serif;
}

Like the --apex-tree-* variables, the tokens are read when the tree renders. After a token change without a render (an OS light or dark flip, or a host app swapping its design system), call tree.refreshTokens().

They resolve below anything the tree sets for itself. A tree already themed through its own options, or through the --apex-tree-* variables, is untouched, while the tokens beat the 'dark' preset and a registered theme. The full order is under Precedence above.

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 ApexTree 2.3.0, an Ignite UI theme on the page can supply the tree'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.

Container styling with canvasStyle

canvasStyle injects arbitrary CSS onto the SVG root container, which is useful for a border, background, or rounded corners around the whole chart:

const tree = new ApexTree(el, {
  canvasStyle: 'border: 1px solid #E2E8F0; border-radius: 12px; background: #fff;',
})

Per-node theming

Any node can override its colors, borders, and fonts via NestedNode.options, which is useful for categorizing roles or highlighting a specific node. See Data Format:

const data = {
  id: 'ceo',
  name: 'Alice',
  options: { nodeBGColor: '#EEF2FF', borderColor: '#6366F1', fontWeight: '700' },
  children: [],
}

Complete dark-theme example

const tree = new ApexTree(document.getElementById('chart'), {
  theme: 'dark',
  nodeWidth: 160,
  nodeHeight: 56,
  borderRadius: '10px',
  fontColor: '#E2E8F0',
  fontFamily: 'Inter, sans-serif',
  edgeColorMode: 'node',
  canvasStyle: 'border-radius: 12px; background: #0F172A;',
})
tree.render(data)

React example

import { ApexTreeChart } from 'react-apextree'

const options = {
  theme: 'dark' as const,
  nodeWidth: 160,
  nodeHeight: 56,
  borderRadius: '10px',
  fontColor: '#E2E8F0',
  edgeColorMode: 'node' as const,
}

export default function ThemedTree() {
  return <ApexTreeChart data={data} options={options} />
}