vue-apextree

vue-apextree

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

Installation

npm install vue-apextree apextree

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

Basic Usage

<script setup lang="ts">
import { ApexTreeChart } from 'vue-apextree';
import type { NestedNode } from 'vue-apextree';

const data: NestedNode = {
  id: '1',
  name: 'CEO',
  children: [
    {
      id: '2',
      name: 'CTO',
      children: [
        { id: '3', name: 'Dev Lead', children: [] },
        { id: '4', name: 'QA Lead', children: [] },
      ],
    },
    {
      id: '5',
      name: 'CFO',
      children: [],
    },
  ],
};
</script>

<template>
  <ApexTreeChart
    :data="data"
    :options="{ width: 800, height: 600, direction: 'top', nodeWidth: 120, nodeHeight: 80 }"
  />
</template>

Setting License Key

If you have a commercial license, set it once at app initialization:

// main.ts
import { setApexTreeLicense } from 'vue-apextree';

setApexTreeLicense('your-license-key');

Props

options

All fields map directly to TreeOptions from the core library — no re-definition in the wrapper. Pass any subset as a plain object; unset fields fall back to core defaults.

Layout

Nodes

Edges

Font

Tooltip

Events

onNodeClick is intentionally excluded from options — use the @node-click emit instead.

<script setup lang="ts">
import { ApexTreeChart } from 'vue-apextree';

const handleNodeClick = (node: unknown) => {
  console.log('Node clicked:', node);
};
</script>

<template>
  <ApexTreeChart :data="data" @node-click="handleNodeClick" />
</template>

Exposed Methods

Access imperative methods via a template ref:

<script setup lang="ts">
import { ref } from 'vue';
import { ApexTreeChart } from 'vue-apextree';
import type { ApexTreeExpose } from 'vue-apextree';

const treeRef = ref<ApexTreeExpose | null>(null);
</script>

<template>
  <ApexTreeChart ref="treeRef" :data="data" />
  <button @click="treeRef?.changeLayout('left')">Rotate</button>
  <button @click="treeRef?.fitScreen()">Fit Screen</button>
  <button @click="treeRef?.collapse('node-id')">Collapse</button>
  <button @click="treeRef?.expand('node-id')">Expand</button>
</template>

Conveniences for the common verbs. Anything not listed is reachable through getGraph(), which returns the fully typed graph instance.

Everything from updateData down requires apextree >= 2.0.0.

getGraph() is typed off the core apextree you have installed, so it also covers expandSubtree, collapseSubtree, expandCard, collapseCard, setExpandedCards, getExpandedCards, getFocusedNodeId, getActivePath, setSelection, getSelection, clearSelection, getRootNodeId and getNodeLabel.

Animated data updates

Changing the data prop reconciles the new dataset into the live tree rather than rebuilding it: surviving nodes spring to their new positions, new ids grow in, and departed ones retract. Collapse state, selection, focus and expanded cards all survive the update.

<script setup lang="ts">
import { ref } from 'vue';
import { ApexTreeChart } from 'vue-apextree';

const data = ref(q1);
</script>

<template>
  <button @click="data = q2">Next quarter</button>
  <ApexTreeChart :data="data" :options="{ direction: 'top' }" />
</template>

This needs apextree >= 2.0.0. On an older core the component falls back to the previous behavior and rebuilds the chart.

Changing options still rebuilds the instance, since options are read at construction. Keep options stable if you update data frequently.

Custom Node Templates

<script setup lang="ts">
import { ApexTreeChart } from 'vue-apextree';
import type { NestedNode } from 'vue-apextree';

interface PersonData {
  title: string;
  imageURL: string;
}

const data: NestedNode<PersonData> = {
  id: '1',
  name: 'Alice',
  data: { title: 'CEO', imageURL: '/alice.png' },
  children: [],
};

const nodeTemplate = (content: string): string => {
  const person = JSON.parse(content) as PersonData;
  return `
    <div style="display:flex;flex-direction:column;align-items:center;height:100%;">
      <img src="https://raw.githubusercontent.com/apexcharts/vue-apextree/HEAD/${person.imageURL}" style="width:50px;height:50px;border-radius:50%;" />
      <div style="font-weight:bold;">${person.title}</div>
    </div>
  `;
};
</script>

<template>
  <ApexTreeChart
    :data="data"
    :options="{ contentKey: 'data', nodeWidth: 150, nodeHeight: 100, nodeTemplate }"
  />
</template>

Reactivity

The component updates automatically when data or options change. A data change is reconciled with animation (see Animated data updates); an options change rebuilds the instance.

<script setup lang="ts">
import { ref } from 'vue';
import { ApexTreeChart } from 'vue-apextree';
import type { NestedNode } from 'vue-apextree';

const data = ref<NestedNode>({
  id: '1',
  name: 'Root',
  children: [],
});

const addChild = () => {
  data.value = {
    ...data.value,
    children: [
      ...data.value.children,
      { id: String(Date.now()), name: 'New Node', children: [] },
    ],
  };
};
</script>

<template>
  <button @click="addChild">Add Child</button>
  <ApexTreeChart :data="data" />
</template>

Data Structure

import type { NestedNode } from 'vue-apextree';

// plain tree (no custom data)
const tree: NestedNode = {
  id: 'root',
  name: 'CEO',
  children: [
    { id: 'vp1', name: 'VP Engineering', children: [] },
    { id: 'vp2', name: 'VP Sales', children: [] },
  ],
};

// typed custom data payload
interface Employee {
  department: string;
  headcount: number;
}

const typedTree: NestedNode<Employee> = {
  id: 'root',
  name: 'CEO',
  data: { department: 'Executive', headcount: 1 },
  children: [],
};

Per-node visual overrides are set via the options field on each NestedNode:

const node: NestedNode = {
  id: 'highlighted',
  name: 'Special Node',
  children: [],
  options: {
    nodeBGColor: '#E8F5E9',
    borderColor: '#43A047',
    fontColor: '#1B5E20',
  },
};

TypeScript Support

import type {
  ApexTreeProps,
  ApexTreeExpose,
  GraphInstance,
  NestedNode,
  TreeOptions,
  TreeDirection,
} from 'vue-apextree';

TreeOptions and NestedNode are re-exported directly from the core apextree package — no local re-definition, so types stay in sync automatically with core releases.

License

vue-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/vue-apextree.git
cd vue-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