Skip to main content

Chord Diagram

Basic Configuration​

The Chord Diagram component is a variation of a network graph where nodes and links are displayed in a circular layout.

component.tsx
<VisSingleContainer data={data}>
  <VisChordDiagram/>
</VisSingleContainer>
Loading...

where data types look like:

type ChordInputNode = {
    id?: string;
}

type ChordInputLink = {
    source: number | string | ChordInputNode;
    target: number | string | ChordInputNode;
    value: number;
}

type ChordData<ChordInputNode, ChordInputLink> = {
  nodes: ChordInputNode[];
  links: ChordInputLink[];
}

Node Label​

You can supply node labels through that data as a property of ChordInputNode, or by using a StringAccessor function in the component:

component.tsx
function Component(props) {
  const data: ChordData = props.data
  const nodeLabel = (d: ChordInputNode) => `${d.id}`

  return (
    <VisChordDiagram nodeLabel={nodeLabel}/>
  )
}
Loading...

Node Label Alignment​

By default, the labels will be placed inside the node with respect to the curve. Alternatively, you can set nodeLabelAlignment to perpendicular:

<VisChordDiagram
  nodeLabel={nodeLabel} 
  nodeLabelAlignment="perpendicular"
/>
Loading...

You can provide color accessors for the nodes, and links to customize the color of your chart.

<VisChordDiagram nodeColor={nodeColor} linkColor={linkColor}/>
Loading...

Circle Customization​

You can change the appearance of your circular chart with the following related properties from Donut:

Hierarchical data​

ChordDiagram supports hierarchical data. When you provide nodeLevels with a list of properties, nodes will be displayed as n distinct layers, where n is the number of properties provided.

Consider the following example, where data has the following type:

const data = {
  nodes: [
    { id: 'A1', group: 'Level 1', subgroup: 'A'},
    { id: 'B1', group: 'Level 1', subgroup: 'B' },
    ...
  ],
  links: [...]
}

Then, by providing this list we can see three distinct layers in the visualization:

component.tsx
import { VisSingleContainer, VisChordDiagram } from '@unovis/react'

function Component(props) {
  const data: ChordData = props.data
  const nodeLevels = [`group`, `subgroup`]

  return (
    <VisSingleContainer data={data}>
      <VisChordDiagram nodeLevels={nodeLevels}/>
    </VisSingleContainer>
  )
}
Loading...

Accessor functions with hierarchical nodes​

Because internal nodes are generated and not provided as apart of the original data, the accessor functions for nodes in ChordDiagram will have a different parameter type of N | ChordHierarchyNode<N>. Leaf nodes will still have the input datum type, N and non-leaf nodes have the following type:

type ChordHierarchyNode<N> = {
  /* The property name (i.e. 'A') */
  key: string;
  /*  Array of descendant nodes */
  values: (N | ChordHierarchyNode<N>)[];
  /* Zero for the root node, and increasing by one for each descendant generation */
  depth: number;
  /* Zero for leaf nodes, and the greatest distance from any descendant leaf for internal nodes */
  height: number;
  /* Aggregated value calcualted from link data */
  value: number;
  /* Key values for the ancestor nodes. i.e ['A', 'Level 1', 'root'] */
  ancestors: string[];
}

In cases where you want to customize the appearance of internal nodes you can refer to this type.

For example, consider the following case where you want a 2-level chart grouped by the key provided in nodeLevels. We can adjust the accessor functions to change the label and color configuration for inner nodes like so:

// Node datum
type N = {
  label: string;
  group: 'A' | 'B' | 'C'
}

const colors =  { A: 'lightgreen', B: 'cornflowerblue', C: 'indigo'}

// Configuration
const nodeLevels = ['group']
const nodeLabel = (d: N | ChordHierarchyNode<N>) => (d as N).label ?? `${d.key}: ${colors[d.key]}`
const nodeColor = (d: N | ChordHierarchyNode<N>) => colors[d.key ?? d.group]
const nodeLabelAlignment = (d: N | ChordHierarchyNode<N>) => d.height > 0 ? 'along' : 'perpendicular'

The result gives us a Chord Diagram with color-coded group data:

<VisChordDiagram
  nodeLevels={nodeLevels} 
  nodeColor={nodeColor} 
  nodeLabel={nodeLabel} 
  nodeLabelAlignment={nodeLabelAlignment}
/>
Loading...

Radius Scale Exponent​

The radiusScaleExponent property affects how the radii scale with each hierarchy level. Increasing this value will result in more distance between each level, while decreasing results in the opposite. Default = 2.

<VisChordDiagram radiusScaleExponent={0.75} nodeLevels={nodeLevels}/>
Loading...

Events​

import { ChordDiagram, ChordNode, ChordRibbon } from '@unovis/vis'

events = {
  [ChordDiagram.selectors.node]: {
    mouseover: (d: ChordNode<N>) => {},
    mouseout: (d: ChordNode<N>) => {},
  },
  [ChordDiagram.selectors.link]: {
    mouseover: (d: ChornRibbon<N>) => {},
    mouseout: (d: ChornRibbon<N>) => {},
  },
}
<VisChordDiagram events={events}/>

CSS Variables​

All supported CSS variables
--vis-chord-diagram-link-fill-color: #cad5f6;
--vis-chord-diagram-link-stroke-color: #777777;
--vis-chord-diagram-link-stroke-opacity: 0.15;
--vis-chord-diagram-label-text-fill-color-bright: #ffffff;
--vis-chord-diagram-label-text-fill-color-dark: #a5abb2;
/* Dark theme */
--vis-dark-chord-diagram-link-fill-color: #575c65;

Component Props​

NameTypeDescription
* required property