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