vue-apexsankey

vue-apexsankey

Vue 3 wrapper for ApexSankey — a JavaScript library for creating Sankey diagrams.

Installation

npm install vue-apexsankey apexsankey

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

Basic Usage

<script setup lang="ts">
import { ApexSankey } from "vue-apexsankey";
import type { GraphData, SankeyOptions } from "vue-apexsankey";

const data: GraphData = {
  nodes: [
    { id: "oil", title: "Oil" },
    { id: "gas", title: "Natural Gas" },
    { id: "coal", title: "Coal" },
    { id: "fossil", title: "Fossil Fuels" },
    { id: "energy", title: "Energy" },
  ],
  edges: [
    { source: "oil", target: "fossil", value: 15, type: "flow" },
    { source: "gas", target: "fossil", value: 20, type: "flow" },
    { source: "coal", target: "fossil", value: 25, type: "flow" },
    { source: "fossil", target: "energy", value: 60, type: "flow" },
  ],
};

const options: Partial<SankeyOptions> = {
  width: 800,
  height: 500,
  nodeWidth: 20,
};
</script>

<template>
  <ApexSankey :data="data" :options="options" />
</template>

License Setup

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

// main.ts
import { createApp } from "vue";
import { setApexSankeyLicense } from "vue-apexsankey";
import App from "./App.vue";

setApexSankeyLicense("your-license-key-here");

createApp(App).mount("#app");

Using Template Refs

<script setup lang="ts">
import { ref, onMounted } from "vue";
import { ApexSankey } from "vue-apexsankey";
import type { ApexSankeyRef } from "vue-apexsankey";

const chartRef = ref<ApexSankeyRef | null>(null);

onMounted(() => {
  if (chartRef.value?.graph) {
    console.log("Max rank:", chartRef.value.graph.maxRank);
  }
});
</script>

<template>
  <ApexSankey ref="chartRef" :data="data" :options="options" />
</template>

Reactivity

The component re-renders automatically when data or options change:

<script setup lang="ts">
import { ref } from "vue";
import { ApexSankey } from "vue-apexsankey";
import type { GraphData, SankeyOptions } from "vue-apexsankey";

const data = ref<GraphData>({
  nodes: [
    { id: "a", title: "A" },
    { id: "b", title: "B" },
  ],
  edges: [{ source: "a", target: "b", value: 10, type: "flow" }],
});

const options = ref<Partial<SankeyOptions>>({ nodeWidth: 20 });
</script>

<template>
  <ApexSankey :data="data" :options="options" />
</template>

Props

SankeyOptions

All Sankey configuration is passed through the options prop. SankeyOptions is an intersection of the sub-interfaces below — pass a partial; any omitted field falls back to its default.

Canvas & layout

Nodes

Edges

Font

Tooltip

Interaction & animation

Accessibility

Data Structure

interface GraphData {
  nodes: SankeyGraphNode[];
  edges: SankeyGraphEdge[];
}

interface SankeyGraphNode {
  id: string;       // unique identifier
  title: string;    // display label
  color?: string;   // override auto-assigned palette color
}

interface SankeyGraphEdge {
  source: string;   // id of upstream node
  target: string;   // id of downstream node
  value: number;    // flow value — determines edge band width
  type: string;     // category label (used for grouping and tooltip)
}

Custom Tooltip

<script setup lang="ts">
import { ApexSankey } from "vue-apexsankey";
import type { GraphData, SankeyOptions } from "vue-apexsankey";

const data: GraphData = {
  nodes: [
    { id: "a", title: "A" },
    { id: "b", title: "B" },
  ],
  edges: [{ source: "a", target: "b", value: 10, type: "flow" }],
};

const options: Partial<SankeyOptions> = {
  enableTooltip: true,
  tooltipTemplate: ({ source, target, value }) => `
    <div style="padding: 8px;">
      <strong>${source?.title}</strong> → <strong>${target?.title}</strong>
      <br />
      Value: ${value}
    </div>
  `,
};
</script>

<template>
  <ApexSankey :data="data" :options="options" />
</template>

Using the Composable

For more control, use the useSankey composable directly:

<script setup lang="ts">
import { ref } from "vue";
import { useSankey } from "vue-apexsankey";
import type { GraphData, SankeyOptions } from "vue-apexsankey";

const containerRef = ref<HTMLElement | null>(null);

const data = ref<GraphData>({
  nodes: [
    { id: "a", title: "A" },
    { id: "b", title: "B" },
  ],
  edges: [{ source: "a", target: "b", value: 10, type: "flow" }],
});

const options = ref<Partial<SankeyOptions>>({ nodeWidth: 20 });

const { graph, isReady, render, destroy, recreate } = useSankey({
  containerRef,
  data,
  options,
});
</script>

<template>
  <div ref="containerRef" style="width: 800px; height: 500px;" />
</template>

TypeScript Support

import type {
  ApexSankeyProps,
  ApexSankeyRef,
  GraphData,
  SankeyGraphNode,
  SankeyGraphEdge,
  SankeyOptions,
  SankeyNode,
  TooltipContent,
  NodeTooltipContent,
} from "vue-apexsankey";

SSR Support

This component is SSR-safe. It renders an empty container on the server and only initializes the chart client-side after the component is mounted.

License

vue-apexsankey 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

• ApexSankey Documentation
• ApexCharts
• License Information