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]);