OrbChartsOrbCharts

Graph Format

graph describes the relationships between nodes. It consists of two kinds of records: nodes and edges. Nodes represent entities, while edges use source and target (both node ids) to describe the relationship between two nodes.

It suits charts that show networks, relationships, or flows, such as a force-directed graph.

When to use

  • Showing "a network of relationships between entities" (social or dependency relationships)
  • Expressing "the flow or connection strength between nodes"
  • Data that has a node / edge graph-theory structure

Data structure

Graph data mixes node and edge records. Nodes use id, name, value, and series; edges additionally require source and target (pointing to node ids):

import type { RawData } from '@orbcharts/core'
 
const data: RawData = [
  // nodes
  { id: 'id0', name: 'label0', value: 19800000, series: 'series1' },
  { id: 'id2', name: 'label2', value: 9800000, series: 'series1' },
  // edge
  { id: 'id14', name: 'label8', series: 'series2', source: 'id0', target: 'id2', value: 100 },
]

Available fields

FieldTypeRequiredDescription
idstringYesUnique identifier; nodes are referenced by edges through it
valuenumber | nullNoThe value of a node or edge
seriesstringNoSeries name; used for grouping and coloring by default
namestringNoDisplay name (e.g. the text shown in a Tooltip)
sourcestringRequired for edgesThe source node id of an edge
targetstringRequired for edgesThe target node id of an edge
dataanyNoCustom attached data, preserved as-is

Tip: Whether a record is treated as an "edge" depends on whether it has both source and target; all other records are treated as "nodes". A node's id is required, and an edge's source / target must match the id of an existing node.

Model data (ModelDataGraph)

After OrbCharts processes RawData, graph data is split into node and edge arrays, forming an overall ModelDataGraph structure:

interface ModelDataGraph {
  nodes: ModelDatumGraphNode[]
  edges: ModelDatumGraphEdge[]
}

The node ModelDatumGraphNode extends ModelDatumBase:

interface ModelDatumGraphNode {
  // From ModelDatumBase
  id: string
  index: number
  modelType: 'graph'
  name: string
  data: any
  value: number | null
  color: string
  // Graph node-specific fields
  series: string
  seriesIndex: number
  category: string
  categoryIndex: number
}

The edge ModelDatumGraphEdge carries, beyond the node fields, source / target and their indices:

interface ModelDatumGraphEdge {
  // From ModelDatumBase
  id: string
  index: number
  modelType: 'graph'
  name: string
  data: any
  value: number | null
  color: string
  // Graph edge-specific fields
  series: string
  seriesIndex: number
  category: string
  categoryIndex: number
  source: ModelDatumGraphNode
  sourceIndex: number
  target: ModelDatumGraphNode
  targetIndex: number
}

Corresponding Plugins

The graph format works with the following Plugins:

PluginCharts
NetworkPlotForce-directed graph

Full example

Below is a relationship chart using NetworkPlot (which shows a force-directed graph by default):

import { OrbCharts } from '@orbcharts/core'
import type { RawData } from '@orbcharts/core'
import { NetworkPlot, Tooltip, Legend } from '@orbcharts/plugin-basic'
 
const data: RawData = [
  // nodes
  { id: 'id0', name: 'label0', value: 19800000, series: 'series1' },
  { id: 'id2', name: 'label2', value: 9800000, series: 'series1' },
  // edge
  { id: 'id14', name: 'label8', series: 'series2', source: 'id0', target: 'id2', value: 100 },
]
 
const chart = new OrbCharts(document.querySelector('#chart')!, {
  data,
  plugins: [
    new NetworkPlot(),
    new Tooltip(),
    new Legend(),
  ],
})
 
// Remember to destroy the chart on unmount to release resources and listeners
// chart.destroy()

Note: OrbCharts fills its container by default (size defaults to 'auto'). Make sure the #chart container has an explicit width and height, otherwise the chart may not be visible. See Core Concepts.