react-apextree

React wrapper for ApexTree - a JavaScript library for creating organizational and hierarchical charts.

Installation

npm install react-apextree apextree

Note: apextree is a peer dependency and must be installed alongside react-apextree.

Basic Usage

import { ApexTreeChart } from "react-apextree";

const data = {
  id: "1",
  name: "CEO",
  children: [
    {
      id: "2",
      name: "CTO",
      children: [
        { id: "3", name: "Dev Lead" },
        { id: "4", name: "QA Lead" },
      ],
    },
    {
      id: "5",
      name: "CFO",
    },
  ],
};

function App() {
  return (
    <ApexTreeChart
      data={data}
      options={{
        width: 800,
        height: 600,
        direction: "top",
        nodeWidth: 120,
        nodeHeight: 80,
      }}
    />
  );
}

Using Imperative Methods

Access methods like changeLayout, collapse, expand, and fitScreen via ref:

import { useRef } from "react";
import { ApexTreeChart, ApexTreeRef } from "react-apextree";

function App() {
  const treeRef = useRef<ApexTreeRef>(null);

  return (
    <div>
      <button onClick={() => treeRef.current?.changeLayout("left")}>Change Layout</button>
      <button onClick={() => treeRef.current?.fitScreen()}>Fit Screen</button>
      <button onClick={() => treeRef.current?.collapse("2")}>Collapse node 2</button>
      <button onClick={() => treeRef.current?.expand("2")}>Expand node 2</button>

      <ApexTreeChart
        ref={treeRef}
        data={data}
        options={{ width: 800, height: 600 }}
      />
    </div>
  );
}

Custom Node Templates

<ApexTreeChart
  data={data}
  options={{
    width: 800,
    height: 600,
    contentKey: "data",
    nodeWidth: 150,
    nodeHeight: 100,
    nodeTemplate: (content) => `
      <div style="display: flex; flex-direction: column; align-items: center; height: 100%;">
        <img
          src="${content.imageURL}"
          style="width: 50px; height: 50px; border-radius: 50%;"
        />
        <div style="font-weight: bold;">${content.name}</div>
      </div>
    `,
  }}
/>

Props

Prop	Type	Default	Description
data	NestedNode	required	Tree data structure
options	Omit<Partial<TreeOptions>, 'onNodeClick'>	-	Tree configuration (see below)
onNodeClick	(node: unknown) => void	-	Callback fired when a node is clicked
className	string	-	CSS class for the container
style	CSSProperties	-	Inline styles for the container

TreeOptions

All tree configuration is passed through the options prop:

Option	Type	Default	Description
width	number | string	400	Width of the container
height	number | string	400	Height of the container
direction	'top' | 'bottom' | 'left' | 'right'	'top'	Direction of tree growth
contentKey	string	'name'	Key for node content
siblingSpacing	number	50	Spacing between siblings
childrenSpacing	number	50	Spacing between parent and children
nodeWidth	number	50	Width of nodes
nodeHeight	number	30	Height of nodes
nodeTemplate	(content: string) => string	-	Custom HTML template for nodes
nodeStyle	string	-	CSS styles for nodes
nodeBGColor	string	'#FFFFFF'	Node background color
nodeBGColorHover	string	'#FFFFFF'	Node background color on hover
borderWidth	number	1	Node border width
borderStyle	string	'solid'	Node border style
borderRadius	string	'5px'	Node border radius
borderColor	string	'#BCBCBC'	Node border color
borderColorHover	string	'#5C6BC0'	Node border color on hover
edgeWidth	number	1	Edge line width
edgeColor	string	'#BCBCBC'	Edge line color
edgeColorHover	string	'#5C6BC0'	Edge line color on hover
fontSize	string	'14px'	Font size
fontFamily	string	-	Font family
fontWeight	string	'400'	Font weight
fontColor	string	'#000000'	Font color
highlightOnHover	boolean	true	Enable highlight on hover
enableToolbar	boolean	false	Show toolbar
enableExpandCollapse	boolean	false	Enable expand/collapse buttons
expandCollapseButtonBGColor	string	-	Expand/collapse button background
expandCollapseButtonBorderColor	string	-	Expand/collapse button border
enableTooltip	boolean	false	Enable tooltips
tooltipTemplate	(content: string) => string	-	Custom tooltip template
tooltipMaxWidth	number	-	Tooltip max width
tooltipMinWidth	number	-	Tooltip min width
tooltipBorderColor	string	-	Tooltip border color
tooltipBGColor	string	-	Tooltip background color
tooltipFontColor	string	-	Tooltip font color
tooltipFontSize	string	-	Tooltip font size
tooltipPadding	number	-	Tooltip padding
tooltipOffset	number	-	Tooltip offset
groupLeafNodes	boolean	false	Stack leaf nodes
groupLeafNodesSpacing	number	-	Spacing when leaf nodes are grouped
canvasStyle	string	-	CSS styles for the canvas

Ref Methods

Method	Description
changeLayout(direction?)	Change tree direction
collapse(nodeId)	Collapse a node
expand(nodeId)	Expand a node
fitScreen()	Fit tree to screen
getGraph()	Get the underlying graph instance

Data Structure

interface NestedNode<T = undefined> {
  id: string;                  // unique identifier
  name: string;                // display label (or use contentKey to point at a different field)
  data: T;                     // custom data payload, available in nodeTemplate / onNodeClick
  children: NestedNode<T>[];   // child nodes; pass [] for leaf nodes
  options?: Partial<TreeOptions>; // per-node visual overrides (font, border, tooltip)
}

TypeScript Support

Full TypeScript support with exported types:

import type {
  ApexTreeProps,
  ApexTreeRef,
  NestedNode,
  TreeOptions,
  GraphInstance,
} from "react-apextree";

Migrating from v1

v2 is a breaking change. All tree configuration options that were previously individual props are now grouped under a single options prop.

Before (v1)

<ApexTreeChart
  data={data}
  width={800}
  height={600}
  direction="top"
  nodeWidth={200}
  nodeHeight={80}
  edgeColor="#ccc"
  fontSize="14px"
  enableExpandCollapse
  onNodeClick={(node) => console.log(node)}
/>

After (v2)

<ApexTreeChart
  data={data}
  onNodeClick={(node) => console.log(node)}
  options={{
    width: 800,
    height: 600,
    direction: "top",
    nodeWidth: 200,
    nodeHeight: 80,
    edgeColor: "#ccc",
    fontSize: "14px",
    enableExpandCollapse: true,
  }}
/>

The className and style props remain at the top level (they style the container element, not the tree).

Updated type imports

- import type { NodeData, NodeOptions, TreeDirection } from "react-apextree";
+ import type { NestedNode, TreeOptions } from "react-apextree";

License

React-Apextree uses the same dual-license model as ApexCharts. See LICENSE for details.

• Free for individuals, non-profits, and small businesses (< $2M revenue)
• Commercial license required for larger organizations

Links

• ApexTree Documentation
• ApexCharts
• License Information

Development

Running the Demo

The package includes a demo app showcasing various features:

# clone the repo
git clone https://github.com/apexcharts/react-apextree.git
cd react-apextree

# install dependencies
npm install
cd demo && npm install && cd ..

# build the library
npm run build

# run the demo
npm run demo

Then open http://localhost:5173 to see the examples.

Available Scripts

• npm run build - Build the library
• npm run dev - Build in watch mode
• npm run typecheck - Run TypeScript type checking
• npm run demo - Run the demo app
• npm run demo:build - Build the demo app