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