ApexTree - Installation and Getting started

The Apextree is a javascript library built on SVG that helps to create organizational or hierarchical charts.

Installation

To add the Apextree to your project and its dependencies, install the package from npm.

npm install apextree

Usage

import ApexTree from 'apextree';

To create a basic tree with minimal configuration, write as follows:

<div id="svg-tree"></div>

 const data = {
   ...(nested data with format provided below)
 }
 const options = {
   width: 700,
   height: 700,
   nodeWidth: 120,
   nodeHeight: 80,
   childrenSpacing: 100,
   siblingSpacing: 30,
   direction: 'top',
   canvasStyle: 'border: 1px solid black;background: #f6f6f6;',
 };
 const tree = new ApexTree(document.getElementById('svg-tree'), options);
 const graph = tree.render(data);

Setting the License

To use ApexTree with a commercial license, set your license key before creating any chart instances:

import ApexTree from 'apextree';

// set license key before creating any charts
ApexTree.setLicense('your-license-key');

const tree = new ApexTree(document.getElementById('svg-tree'), options);
const graph = tree.render(data);

Tree Options

The layout can be configured by passing a second argument to ApexTree with the properties listed below.

Layout & Canvas

Option	Type	Default	Description
width	number | string	'100%'	Width of the canvas. Accepts a pixel number or CSS percentage string.
height	number | string	'auto'	Height of the canvas. 'auto' sizes to content.
viewPortWidth	number	800	Internal SVG viewport width in pixels.
viewPortHeight	number	600	Internal SVG viewport height in pixels.
direction	'top' | 'bottom' | 'left' | 'right'	'top'	Direction the tree grows from the root node.
contentKey	string	'name'	Key in the data object used as the node display label. Set to 'data' to pass a structured object to nodeTemplate.
siblingSpacing	number	50	Horizontal distance between sibling nodes in pixels.
childrenSpacing	number	50	Vertical distance between a parent node and its children in pixels.
canvasStyle	string	''	Arbitrary CSS injected onto the SVG root container element.
containerClassName	string	'root'	CSS class name for the root SVG container element.
theme	'light' | 'dark' | 'custom'	'light'	Built-in theme preset. 'dark' uses slate backgrounds for dark-mode apps. 'custom' disables built-in CSS variable injection so host-page variables take precedence.

Interaction & Features

Option	Type	Default	Description
highlightOnHover	boolean	true	Highlight the hovered node and its connecting edges.
enableAnimation	boolean	true	Animate node expansion/collapse transitions.
enableExpandCollapse	boolean	true	Show expand/collapse buttons on nodes that have children.
enableExpandCollapseZoom	boolean	true	Re-fit the viewBox to the new tree bounds on collapse/expand. Set to false to keep the viewBox fixed.
enableToolbar	boolean	false	Show the zoom/pan toolbar.
enableSearch	boolean	false	Show a search input in the toolbar. Filters nodes by label, highlights matches, and centers on the first match on Enter.
enableSelection	'single' | 'multi' | false	false	Node selection mode. 'single' allows one selected node at a time. 'multi' allows toggling multiple nodes. Selected nodes get aria-selected="true" and a visible ring.
enableBreadcrumb	boolean	false	Show a breadcrumb trail above the chart. Updates on node click to show the path from root to the selected node.
groupLeafNodes	boolean	false	Stack leaf nodes vertically instead of spreading them horizontally.
groupLeafNodesSpacing	number	10	Spacing between stacked leaf nodes in pixels.
onNodeClick	(node: unknown) => void	undefined	Callback fired when the user clicks a node. Receives the raw node data object.

Node Styling

Option	Type	Default	Description
nodeWidth	number	50	Width of each node in pixels.
nodeHeight	number	30	Height of each node in pixels.
nodeTemplate	(content: unknown) => string	built-in	Custom function returning an HTML string rendered inside each node. Receives the value at contentKey.
nodeClassName	string	'apextree-node'	CSS class name added to every node element.
nodeStyle	string	''	Inline CSS string applied to each node element.
nodeBGColor	string	'#FFFFFF'	Default background color of nodes.
nodeBGColorHover	string	'#FFFFFF'	Background color of nodes on hover.
nodeShadow	string	'0 1px 2px rgba(16,24,40,0.06), 0 1px 3px rgba(16,24,40,0.1)'	CSS box-shadow applied to nodes. Set to empty string to disable.
nodeShadowHover	string	'0 4px 6px -1px rgba(16,24,40,0.1), 0 2px 4px -2px rgba(16,24,40,0.1)'	CSS box-shadow applied to nodes on hover. Set to empty string to keep constant.
borderWidth	number	1	Border width of nodes in pixels.
borderStyle	string	'solid'	CSS border-style for nodes.
borderRadius	string	'10px'	CSS border-radius for nodes.
borderColor	string	'#E4E7EC'	Border color of nodes in their default state.
borderColorHover	string	'#5C6BC0'	Border color of nodes on hover.

Edge (Connector) Styling

Option	Type	Default	Description
edgeStyle	'orthogonal' | 'curved' | 'straight'	'orthogonal'	Shape of connecting lines. 'orthogonal' draws right-angle elbows. 'curved' draws smooth Bézier curves. 'straight' draws direct lines.
edgeWidth	number	1	Stroke width of connecting lines in pixels.
edgeColor	string	'#D0D5DD'	Color of connecting lines between nodes.
edgeColorHover	string	'#5C6BC0'	Color of connecting lines when highlighted on hover.
edgeColorMode	'default' | 'node'	'default'	'default' uses the global edgeColor. 'node' inherits the borderColor of the child node each edge connects into, giving each branch a matching color.

Expand/Collapse Button & Badge

Option	Type	Default	Description
expandCollapseButtonBGColor	string	'#FFFFFF'	Background color of the expand/collapse button.
expandCollapseButtonBorderColor	string	'#E4E7EC'	Border color of the expand/collapse button.
collapseBadgeEnabled	boolean	true	Show the collapse-count badge on collapsed nodes.
collapseBadgeThreshold	number	1	Minimum number of hidden children required before the badge appears.
collapseBadgeBGColor	string	'#5C6BC0'	Background color of the collapse-count badge.
collapseBadgeFontColor	string	'#FFFFFF'	Font color of the collapse-count badge.
collapseBadgeFontSize	string	'12px'	Font size of the collapse-count badge.

Typography

Option	Type	Default	Description
fontColor	string	'#101828'	CSS color for node text.
fontFamily	string	system default	CSS font-family for node text. Falls back to the page default when empty.
fontSize	string	'14px'	CSS font-size for node text.
fontWeight	string	'400'	CSS font-weight for node text.

Tooltip

Option	Type	Default	Description
enableTooltip	boolean	false	Show a tooltip on node hover.
tooltipId	string	'apextree-tooltip-container'	HTML id for the tooltip container element.
tooltipTemplate	(content: string) => string	built-in	Custom function returning an HTML string for the tooltip content.
tooltipMaxWidth	number | undefined	undefined	Maximum width of the tooltip in pixels.
tooltipMinWidth	number	100	Minimum width of the tooltip in pixels.
tooltipBorderColor	string	'#BCBCBC'	Border color of the tooltip.
tooltipBGColor	string	'#FFFFFF'	Background color of the tooltip.
tooltipFontColor	string	'#000000'	Font color of tooltip text.
tooltipFontSize	string	'12px'	Font size of tooltip text.
tooltipPadding	number	8	Inner padding of the tooltip in pixels. Set to 0 when using a custom tooltipTemplate.
tooltipOffset	number	10	Distance between the tooltip and the cursor in pixels.

Accessibility

Option	Type	Default	Description
a11y	{ enabled?: boolean, label?: string }	{ enabled: true, label: 'Organizational chart' }	WCAG 2.1 AA accessibility. Adds ARIA tree semantics, keyboard navigation, and visible focus indicators. Set label to customise the SVG aria-label.

Node Templates

Default template

When contentKey is 'name' (the default), the built-in template renders a single centered label:

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

Built-in org-chart card

When contentKey is set to 'data' and the data object contains any of imageURL, title, subtitle, badge, or accentColor, the built-in template automatically renders a structured org-chart card with avatar, name, title, subtitle, optional badge, and optional accent stripe — no custom nodeTemplate needed.

const data = {
  id: 'ceo',
  name: 'Alice',
  data: {
    name: 'Alice Johnson',
    title: 'Chief Executive Officer',
    subtitle: 'Executive',
    imageURL: 'https://example.com/avatar.jpg',
    accentColor: '#6366f1',
    badge: {text: 'Active', color: '#EEF2FF'},
  },
  children: [],
};

const options = {
  contentKey: 'data',
  nodeWidth: 200,
  nodeHeight: 80,
};

Custom template

Pass a nodeTemplate function for full control over node rendering:

const options = {
  contentKey: 'data',
  nodeTemplate: (content) => `
    <div style="display: flex; align-items: center; gap: 8px; padding: 8px;">
      <img src="${content.img}" style="width: 32px; height: 32px; border-radius: 50%;" />
      <div>
        <div style="font-weight: 600;">${content.name}</div>
        <div style="font-size: 11px; color: #666;">${content.role}</div>
      </div>
    </div>`,
};

Per-Node Options

Individual nodes can override global styling via an options object. This accepts the same node, font, and tooltip options as the global configuration:

const data = {
  id: 'ceo',
  name: 'CEO',
  options: {
    nodeBGColor: '#EEF2FF',
    nodeBGColorHover: '#EEF2FF',
    borderColor: '#A5B4FC',
    borderColorHover: '#6366F1',
  },
  children: [
    {
      id: 'cto',
      name: 'CTO',
      options: {
        nodeBGColor: '#ECFDF5',
        borderColor: '#6EE7B7',
      },
      children: [],
    },
  ],
};

Expected Data Format

{
  "id": "1",
  "name": "A",
  "children": []
}

Each node object requires:

• id — unique identifier. Must be unique across all nodes for edge highlighting and selection to work correctly.
• name — display label rendered inside the node (when using the default contentKey: 'name').
• children — array of child node objects. Pass an empty array [] for leaf nodes.
• data (optional) — arbitrary data payload. When using contentKey: 'data', this object is passed to nodeTemplate.
• options (optional) — per-node style overrides (see Per-Node Options).

Example

const data = {
  id: '1',
  name: 'A',
  children: [
    {
      id: '2',
      name: 'B',
      children: [
        {
          id: '3',
          name: 'C',
          children: [],
        },
        {
          id: '4',
          name: 'D',
          children: [],
        },
      ],
    },
  ],
};

Graph API Methods

The tree.render(data) call returns a graph instance with the following public methods:

Layout & View

Method	Description
changeLayout(direction)	Switch the tree direction dynamically ('top', 'bottom', 'left', 'right').
fitScreen()	Re-fit the viewBox to show all visible nodes.
centerOnNode(nodeId)	Pan and zoom to center a specific node in the viewport.

Expand & Collapse

Method	Description
collapse(nodeId)	Programmatically collapse a node.
expand(nodeId)	Programmatically expand a node.

Selection

Method	Description
getSelection()	Returns an array of currently selected node IDs.
setSelection(ids)	Programmatically set selected nodes by ID array.
clearSelection()	Clear all selections.
onSelectionChange(listener)	Register a callback fired whenever the selection changes. Pass null to remove.

Search

Method	Description
findNodesByQuery(query)	Returns an array of node IDs whose labels match the query string.
setSearchHighlight(matchIds)	Highlight specific nodes as search results. Pass an empty array to clear.

Data & Nodes

Method	Description
construct(data)	Replace the tree data and re-render.
getNodeMap()	Returns a map of all node IDs to their node objects.
getRootNodeId()	Returns the ID of the root node.
getNodeLabel(nodeId)	Returns the display label for a node.

Breadcrumb

Method	Description
setBreadcrumbHandler(handler)	Register a callback for breadcrumb segment clicks. Pass null to remove.

Export

Method	Description
exportToSvg()	Export the current tree as an SVG file download.

Example

const tree = new ApexTree(document.getElementById('svg-tree'), options);
const graph = tree.render(data);

// Change layout direction
graph.changeLayout('left');

// Collapse a node programmatically
graph.collapse('node-2');

// Listen for selection changes
graph.onSelectionChange((ids) => {
  console.log('Selected:', ids);
});

// Search and highlight
const matches = graph.findNodesByQuery('engineer');
graph.setSearchHighlight(matches);
graph.centerOnNode(matches[0]);