Options

Width of the canvas. Accepts a pixel number or CSS percentage string.

Height of the canvas. Use 'auto' to size to content.

Controls the direction the tree grows from the root node.

Available Options:

• top: root at the top, children flow downward (default)
• bottom: root at the bottom, children flow upward
• left: root on the left, children flow rightward
• right: root on the right, children flow leftward
• radial: root at the centre, each depth on its own ring

Where each rank is placed along the growth axis.

Available Options:

• tree (default): every node sits at a depth matching its own
• cluster: all leaves are pinned to the deepest rank, lining up on the outer ring in a radial layout or the bottom row in a cartesian one

Internal nodes keep their natural depth either way. See Radial and Dendrogram Layouts.

Key in the data object used as the node display label.

Horizontal distance between sibling nodes in pixels.

Vertical distance between a parent node and its children in pixels.

Highlight the hovered node and its connecting edges.

CSS class name for the root SVG container element.

Arbitrary CSS injected onto the SVG root container element.

Show the zoom/pan toolbar.

Animate node positions, enter/exit, edges and the camera. With false, renders and reflows land at their final state immediately and node positions are readable synchronously after render().

Available Options:

• true (default)
• false

Tuning for the spring-driven reflow. Springs carry velocity, so a toggle that arrives mid-animation redirects instead of restarting. See Motion and Animation.

Spring feel used for node and camera motion.

Available Options:

• crisp (default): settles quickly without visible overshoot
• gentle: softer, for large reflows
• snappy: faster

How a reflow propagates outward from the toggled node.

Available Options:

• wave (default): nodes are staggered by their graph distance from the pivot, so a subtree unfolds outward
• none: every node moves together

Stack leaf nodes vertically instead of spreading them horizontally.

Internal SVG viewport width in pixels.

Internal SVG viewport height in pixels.

Width of each node in pixels. A node's own options.nodeWidth overrides this for that node; edges anchor to each card's own half-size, so mixed-size siblings separate correctly.

Height of each node in pixels. Overridable per node via options.nodeHeight.

Measure each card's content and size its height to fit, keeping the width fixed. Precedence is explicit per-node height, then measured, then the global nodeHeight. Measurement needs a DOM, so it returns nothing under SSR or jsdom. Cartesian directions only: grouped-leaf and radial layouts stay uniform. See Node Sizing and Expandable Cards.

Measure content and size each node to fit.

Available Options:

• false (default)
• true

Lower clamp for the measured height in pixels, so short cards keep a baseline. 0 means no floor.

Upper clamp for the measured height in pixels. Taller content is capped and clipped by the node's overflow: hidden. 0 means no cap.

Extra vertical padding added to the measured content height, in pixels.

A card can expand in place to reveal a detail section, which is separate from expanding a node's children. The expandCard / collapseCard / toggleCard methods work regardless of this option; expansion only grows the card when the height can change, so pair it with autoNodeHeight.

Toggle a node's card by clicking anywhere on it rather than only the chevron. Clicks on the expand/collapse button still toggle children.

Available Options:

• false (default)
• true

Custom function returning an HTML string rendered inside each node.

nodeTemplate: (content) => {
  return `
    <div style='display:flex;justify-content:center;
      align-items:center;text-align:center;height:100%;'>
      ${content}
    </div>
  `;
}

The context passed to the template carries an expanded flag and a lod tier, so a custom card can render its own detail section and its own simplified tiers. See Custom Node Templates.

Stamp your own classes and data-* attributes on each node's wrapper <g> without replacing its nodeTemplate content. Return { className, attributes }, or nothing to leave the wrapper untouched. Attributes ApexTree uses for node identity are never overwritten, and a per-node hook set via NestedNode.options.nodeWrapper wins over the global one.

The context carries id, name, data, depth, collapsed, expanded and hasChildren.

nodeWrapper: ({ id, depth, collapsed }) => ({
  className: collapsed ? 'is-collapsed' : '',
  attributes: { 'data-depth': depth, 'data-menu-target': id },
})

Stamping happens on the SVG group outside the foreignObject, so it is free of the Safari foreignObject CSS constraints that apply to nodeTemplate. Attach delegated listeners on the container to react to them.

Load a node's children on first expand. Mark the node hasChildren: true with no children, and expanding it shows a spinner while this function settles, then splices the returned nodes in and reflows.

The context carries the node's id, name and raw data.

loadChildren: async ({ id }) => {
  const res = await fetch(`/api/reports/${id}`)
  return res.json()
}

Return an empty array for a node that turned out to have none, and its expand affordance is dropped. A rejected promise leaves the node collapsed so the user can retry. See Lazy Children.

Default background color of nodes.

Background color of nodes on hover.

CSS class name added to every node element.

Inline CSS string applied to each node element.

Callback fired when the user clicks a node. Receives the raw node data object.

onNodeClick: (node) => {
  console.log('Clicked:', node);
}

Border width of nodes in pixels.

CSS border-style for nodes.

CSS border-radius for nodes.

Border color of nodes in their default state.

Border color of nodes on hover.

Show expand/collapse buttons on nodes that have children.

Background color of the expand/collapse button.

Diameter of the expand/collapse button in pixels. Purely visual: the button carries an invisible hit area of max(size + 4, 24), so shrinking it never drops the tap target below the WCAG 2.2 SC 2.5.8 minimum of 24px. The chrome grows 15% on hover about its own centre while the hit area stays put.

Color of the +/- glyph inside the expand/collapse button. Set this alongside expandCollapseButtonBGColor when theming, or the glyph can end up invisible against the button fill. Also settable as the --apex-tree-expand-btn-icon CSS variable.

Color of an opaque ring drawn just outside the expand/collapse button, so it punches a clean hole through the node border and the incoming edge instead of merging into them. Set it to whatever is painted behind the nodes, usually the page or container background. Empty disables the halo, because the library cannot know that color. Also settable as the --apex-tree-expand-btn-halo CSS variable.

Border color of the expand/collapse button.

Show the collapse-count badge on collapsed nodes.

Background color of the collapse-count badge.

Font color of the collapse-count badge.

Font size of the collapse-count badge.

Minimum number of hidden children required before the badge appears.

Show a count badge in the top-right corner of every node, whether it is expanded or collapsed. Unlike the collapse badge, which only appears on a collapsed node, this one is always visible.

Available Options:

• false (default)
• true

What the count badge number represents.

Available Options:

• descendants (default): every node beneath this one
• children: direct children only
• data: a value read from the node's own data at countBadgeDataKey

Per-node field read for the badge number when countBadgeSource is 'data'. The value is coerced with Number(...); non-numeric or missing values render no badge.

Minimum count required before the badge appears, which hides zero and low counts.

Background color of the count badge.

Font color of the count badge.

Font size of the count badge. Accepts a CSS length.

Spacing between stacked leaf nodes when groupLeafNodes is true, in pixels.

Color of the connecting lines between nodes.

Color of connecting lines when highlighted on hover.

Stroke width of connecting lines in pixels.

Styling for the "active path": a marching dash that flows along the lineage set by graph.setActivePath(ids). Plain SVG plus injected keyframes, and it respects reduced motion by highlighting the path without animating it. See Focus Mode and the Active Path.

Stroke color of an active, flowing edge.

Stroke width of an active edge, in pixels.

Flow speed in SVG units per second, which is how fast the dashes travel.

Length of each dash in the marching pattern, in pixels.

Gap between dashes in the marching pattern, in pixels.

Direction the dashes travel.

Available Options:

• toChild (default): flows root to leaf
• toParent: flows leaf to root

Set the active path to a node's lineage automatically when focus mode spotlights it, and clear it on clearFocus().

Available Options:

• false (default)
• true

Show a tooltip on node hover.

HTML id for the tooltip container element.

Custom function returning an HTML string for the tooltip content.

tooltipTemplate: (content) => {
  return `
    <div style='display:flex;justify-content:center;
      align-items:center;text-align:center;height:100%;'>
      ${content}
    </div>
  `;
}

Maximum width of the tooltip in pixels. undefined means unconstrained.

Minimum width of the tooltip in pixels.

Inner padding of the tooltip in pixels. Set to 0 when using a custom tooltipTemplate.

Distance between the tooltip and the cursor in pixels.

Background color of the tooltip.

Border color of the tooltip.

Font color of tooltip text.

Font size of tooltip text.

CSS color for node text.

CSS font-family for node text. Falls back to the page default when empty.

CSS font-size for node text.

CSS font-weight for node text.

WCAG 2.1 AA accessibility options for the tree chart.

Enable ARIA semantics and keyboard navigation.

Override the default aria-label ("Organizational chart") on the root SVG.

Built-in color theme preset for the chart.

Available values: 'light' | 'dark' | 'custom'

Use 'custom' to fully control colors via the individual color options.

Show a breadcrumb trail above the chart that tracks the currently focused node path.

Automatically zoom the viewport to fit the visible subtree when a node is expanded or collapsed.

Enable the built-in search bar that highlights matching nodes in the tree.

Enable node selection. Controls the selection mode.

Available values: 'single' | 'multi' | false

• 'single': only one node can be selected at a time
• 'multi': multiple nodes can be selected simultaneously
• false: selection is disabled

Spotlight a single node: everything outside its lineage and visible subtree dims, and the camera springs to frame it. Escape, a re-click, or clearFocus() restores the full view. The dim is applied by paint order rather than opacity on the cards, and it survives a collapse while focused. See Focus Mode and the Active Path.

Focus a node when its card is clicked. Clicks on the expand/collapse button keep toggling the subtree.

Available Options:

• false (default)
• true

Strength of the dim applied outside the focused lineage and subtree, from 0 (no dim) to 1 (fully hidden).

Render simplified node content as the tree is zoomed out. Node geometry is fixed across tiers: the layout is computed once and crossing a threshold only swaps what renders inside each node's box, so nothing moves and the camera is untouched. See Semantic Zoom.

Re-tier node content by how wide a node appears on screen.

Available Options:

• false (default)
• true

On-screen node width in CSS pixels at or below which a node drops from the full tier to 'compact' (name and role). Must be greater than dotBelow.

On-screen node width in CSS pixels below which a node drops to 'dot', a color slab carrying just the name.

Add a command palette overlay opened with Cmd/Ctrl + K. Type to jump to a node by fuzzy label match, or run a quick action: expand all, collapse all, fit to screen. A plain DOM overlay, keyboard-navigable, dismissed with Escape. See Command Palette.

Available Options:

• false (default)
• true

Determines how connecting edge colors are resolved.

Available values: 'default' | 'node'

• 'default': edges use edgeColor / edgeColorHover
• 'node': edges inherit the color of the source node

Shape of the connecting lines between nodes.

Available values: 'curved' | 'orthogonal' | 'straight'

CSS box-shadow value applied to each node in its default state.

CSS box-shadow value applied to each node on hover.

Toggle a node's expansion when its body is clicked, in addition to the dedicated +/- button. The cursor becomes a pointer on clickable nodes, and the toggle fires before onNodeClick so the user callback sees the post-toggle node state.

Available Options:

• false (default)
• true

Allow mouse-wheel zoom and drag-to-pan on the canvas. Set to false to lock the viewport and hide the toolbar's zoom buttons.

Available Options:

• true (default)
• false

Caps how far the camera zooms in when it re-fits after an expand or collapse, so a view of a few remaining nodes does not balloon to fill the canvas. The fitted view always spans at least this many node widths and heights, centred on the visible nodes. Larger means less zoom-in; 0 disables the cap and fits tightly.

The cap never shrinks the chart below 1:1, so a chart narrower than maxZoomNodeSpan node widths (a small card, a dashboard tile) keeps its tight fit instead of being scaled down on every collapse. Only affects the auto-fit path, so it needs enableExpandCollapseZoom; focus mode keeps its own tighter framing.

Horizontal padding around the rendered tree, in pixels. Adds breathing room between the leftmost/rightmost nodes (and any external labels that extend past them) and the SVG viewBox edge.

Vertical padding around the rendered tree, in pixels. Useful when leaf nodes have rotated externalLabel content that extends past the marker bounds.

Render the node's label as an SVG <text> element positioned outside the node bounds instead of inside the nodeTemplate. The node box still renders (background, border, border-radius), so pair with a small nodeWidth / nodeHeight and borderRadius: '50%' for a marker-style look with a floating label.

When externalLabel.enabled resolves to true for a node, the in-node template is suppressed for that node. Each field can also be set per-node via NestedNode.options.externalLabel, layered onto the global config.

Render the label outside the node bounds. When false, the in-node nodeTemplate is used as before.

Available Options:

• false (default)
• true

Horizontal placement of the label relative to the node.

Available Options:

• 'center' (default): label is centered on the node horizontally
• 'left': label sits to the left of the node (text is right-anchored)
• 'right': label sits to the right of the node (text is left-anchored)

Vertical placement of the label relative to the node.

Available Options:

• 'middle' (default): label is centered on the node vertically
• 'top': label sits above the node (text is bottom-anchored)
• 'bottom': label sits below the node (text is top-anchored)

Additional horizontal pixel offset applied after externalLabel.align.

Additional vertical pixel offset applied after externalLabel.verticalAlign.

Rotation in degrees, applied around the label anchor. Use 90 for top-to-bottom vertical labels and -90 for bottom-to-top.

How to thin external labels that would overlap in a dense radial layout. Inner rings have little arc length, so labels on crowded rings collide. Only applies to direction: 'radial' and is ignored for cartesian layouts; the spacing threshold is derived from the label fontSize.

Available Options:

• none (default): render every label, which may overlap when dense
• hide: hide labels that lack tangential room on their ring, keeping a maximal, evenly spaced subset; well-separated labels always survive
• leaves: additionally drop every inner-node label, labelling only leaves, then still thinning crowded leaves by arc length

Override the global fontColor for the external label only.

Override the global fontFamily for the external label only.

Override the global fontSize for the external label only.

Override the global fontWeight for the external label only.

Where the built-in org-card places the avatar. Custom nodeTemplates receive this through the template context.

Available values: 'left' | 'top'

• 'left' (default): avatar beside the text
• 'top': avatar centered above the text (below it for direction: 'bottom', so it sits on the parent-facing edge)

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

Text and layout direction.

Available values: 'ltr' | 'rtl' | 'auto'

• 'ltr' (default): left-to-right
• 'rtl': mirrors the tree horizontally and sets dir="rtl" on the container, so node text and the search/breadcrumb chrome flow right-to-left. Tuned for the vertical 'top' and 'bottom' growth directions.
• 'auto': defers to the document or element's inherited direction

This is separate from the top-level direction option, which sets the tree's growth direction.

Overrides for user-facing strings. Accepts a partial set; unset keys keep their English defaults. Plain labels are strings; strings that embed runtime data are functions.

Root SVG aria-label. The legacy a11y.label option still overrides this.

Placeholder text for the search input.

aria-label for the search input.

Function that builds the search match-count text from the match count, so each locale controls its own pluralization.

aria-label for the breadcrumb <nav>.

aria-label for the expand button.

aria-label for the collapse button.

Function that builds each node's aria-label from a context object (name, level, position, total, and optional state), so translators can produce a grammatically correct label.

Expand-button aria-label while a node's children are lazy-loading.

aria-label for the chevron that expands a node's card.

aria-label for the chevron that collapses a node's card.

aria-label for the command-palette dialog.

Placeholder text for the command-palette input.

Label for the command-palette "expand all" action.

Label for the command-palette "collapse all" action.

Label for the command-palette "fit to screen" action.

Empty-state text shown when a command-palette query matches nothing.