v-network-graph

The library is built around three core design principles:

• Reactive: All primitive data (nodes, edges, positions, styles) are provided from the outside. Because it uses Vue's reactivity system, you can modify this data at any time to reactively add/remove objects, move nodes, or change appearances.
• Highly Customizable: Supports both static specifications and dynamic changes based on the values of fields contained within node and edge data.
• Extendable: Provides a mechanism to add custom SVG elements and actions to handle application-specific visualization requirements.

To use v-network-graph in Nuxt 3, follow these two steps:

1. Add the CSS to your nuxt.config.ts.
2. Create a plugin file at plugins/v-network-graph.ts to register the component.

// nuxt.config.ts
import { defineNuxtConfig } from "nuxt3"

export default defineNuxtConfig({
  css: ["v-network-graph/lib/style.css"],
})

// plugins/v-network-graph.ts
import { defineNuxtPlugin } from "#app"
import VNetworkGraph from "v-network-graph"

export default defineNuxtPlugin(nuxtApp => {
  nuxtApp.vueApp.use(VNetworkGraph)
})

After installing, register the plugin in your main.ts file. You must also import the component's CSS file to ensure correct styling.

// main.ts
import { createApp } from "vue"
import VNetworkGraph from "v-network-graph"
import "v-network-graph/lib/style.css"
import App from "./App.vue"

const app = createApp(App)

app.use(VNetworkGraph)
app.mount("#app")

Install the package using npm to use the interactive SVG-based network graph component in your Vue 3 project.

npm install v-network-graph

Many configuration properties in v-network-graph support both literal values and callback functions. This allows you to define styles or behaviors that depend on the specific object (node, edge, or path) being rendered.

• Literal Values: Provide a direct value (e.g., color: 'red').
• Callback Functions: Provide a function that receives the target object as an argument and returns the desired value (e.g., color: (node) => node.color).

This pattern is used extensively in NodeConfig, EdgeConfig, and PathConfig via the CallableValue and CallableValues types.

You can install v-network-graph globally in your Vue application using the app.use() method. This automatically registers all available components (such as VNetworkGraph) with the Vue instance, making them available for use in your templates.

import { createApp } from 'vue'
import vNetworkGraph from 'v-network-graph'

const app = createApp({ /* ... */ })
app.use(vNetworkGraph)
app.mount('#app')

The component uses reactive nodes and edges objects. Nodes are keyed by an ID, and edges are keyed by an ID with source and target properties pointing to node IDs. Pass these to the <v-network-graph /> component via the :nodes and :edges props.

<script setup lang="ts">
  const nodes = {
    node1: { name: "Node 1" },
    node2: { name: "Node 2" },
    node3: { name: "Node 3" },
    node4: { name: "Node 4" },
  }
  const edges = {
    edge1: { source: "node1", target: "node2" },
    edge2: { source: "node2", target: "node3" },
    edge3: { source: "node3", target: "node4" },
  }
</script>

<template>
  <v-network-graph
    class="graph"
    :nodes="nodes"
    :edges="edges"
  />
</template>

<style>
.graph {
  width: 800px;
  height: 600px;
  border: 1px solid #000;
}
</style>

The useStates composable is exported for advanced visualization tasks. Note that this is considered an advanced API and may be subject to breaking changes in future versions.

import { useStates } from 'v-network-graph'

// Use within a Vue setup function
const { /* states */ } = useStates()

Use the defineConfigs function to create a type-safe configuration object for the graph. This function accepts a UserConfigs object, which is a recursive partial of the core Configs interface. This allows you to specify only the parts of the node, edge, path, or view settings you wish to customize.

defineConfigs ensures that your configuration object is correctly typed against the internal Configs structure, providing autocompletion and validation for properties like node, edge, path, and view.

import { defineConfigs } from 'v-network-graph';

const myConfigs = defineConfigs({
  node: {
    normal: {
      color: 'red',
      radius: 10
    }
  },
  edge: {
    type: 'straight'
  }
});

Use getFullConfigs to retrieve the complete set of default configuration objects used by the library.

import { getFullConfigs } from 'v-network-graph'

const configs = getFullConfigs()

The library provides built-in layout algorithms to position nodes in the graph. You can import SimpleLayout and GridLayout to use them with the graph component.

import { SimpleLayout, GridLayout } from 'v-network-graph'

// Example usage in a component context
const layout = new SimpleLayout()

The library uses EdgeEntry to represent items intended for display. An EdgeEntry can be either a SingleEdgeItem (representing a specific edge) or a SummarizedEdgeItem (representing a group of edges that have been collapsed/summarized).

• SingleEdgeItem: Contains the edge object and standard display properties like id, summarized (false), key, and zIndex.
• SummarizedEdgeItem: Contains a group of type EdgeGroup and standard display properties like id, summarized (true), key, and zIndex.

export type EdgeEntry = SummarizedEdgeItem | SingleEdgeItem;

export interface SingleEdgeItem {
  id: string;
  summarized: false;
  key: string;
  zIndex: number;
  edge: Edge;
}

export interface SummarizedEdgeItem {
  id: string;
  summarized: true;
  key: string;
  zIndex: number;
  group: EdgeGroup;
}