Chord Chart

The Chord Chart draws a ring of arcs, one per group, and connects them with ribbons whose width encodes the flow between each pair. It suits a square matrix of group-to-group volumes where both directions of a relationship matter: migration between regions, trade between sectors, hand-offs between teams. palette sets the group colors, padAngle and padWidth control the gap between arcs, and legend and format handle the labelling. Arcs enter first, ribbons follow; hovering an arc dims the other arcs and every ribbon it is not attached to. The target can be a Canvas, an SVG context or a terminal.

NOTE

For the full API, see the Charts API Reference.

Example

Customize

Arc gap2

Engineering#7cacf8Design#6dd5b1Marketing#b197fcSales#f7c97e

Show legendPositionTopBottomLeftRight

Show titleTitle text

FormatDefaultNumberPercentageDateString

Padding16

ThemeAutoLightDarkColorblind

AnimateDuration (ms)1000

Usage

import {
    createChordChart,
} from '@ripl/charts';

const chart = createChordChart('#container', {
    groups: ['A', 'B', 'C'],
    matrix: [
        [0, 10, 20],
        [10, 0, 15],
        [20, 15, 0],
    ],
});

Data Format

A chord chart is driven by a square matrix rather than a row-per-item dataset. groups names each row/column, and matrix[i][j] is the flow from group i to group j:

const groups = ['Engineering', 'Design', 'Marketing'];

const matrix = [
    //  Eng  Des  Mkt
    [0, 5, 10], // from Engineering
    [5, 0, 6], //  from Design
    [10, 6, 0], //  from Marketing
];

The diagonal is normally 0 (a group does not flow to itself), and the matrix must be the same length as groups in both dimensions.

Options

A full configuration for this chart. The options every chart shares — padding, title, animation, theme and the rest — behave the same everywhere and are documented on Shared Options.

createChordChart('#container', {
    groups: ['Engineering', 'Design', 'Marketing', 'Sales'],
    // Square flow matrix: matrix[i][j] is the flow from groups[i] to groups[j].
    matrix,
    // One color per group, positional.
    palette: ['#7cacf8', '#6dd5b1', '#b197fc', '#f7c97e'],
    // Gap between adjacent group arcs, in pixels — a constant width whatever the radius.
    padWidth: 2,
    // Deprecated: an angular gap, in radians, taken out of the ring before the arcs are sized.
    // Ignored while `padWidth` is set.
    padAngle: 0.04,
    legend: { position: 'right' },
    format: 'number',
});

Events

Subscribe with chart.on(...). A handler receives an Event object, not the payload directly — the payload is on event.data, and carries the interacted datum plus its { x, y } anchor in chart pixels. event.target and event.stopPropagation() are also available.

// Emitted when an outer arc is clicked.
chart.on('segmentclick', event => console.log(event.data)); // event.data: ChordChartSegmentEvent
// Emitted when the pointer enters an outer arc.
chart.on('segmententer', event => console.log(event.data)); // event.data: ChordChartSegmentEvent
// Emitted when the pointer leaves an outer arc.
chart.on('segmentleave', event => console.log(event.data)); // event.data: ChordChartSegmentEvent
// Emitted when a ribbon is clicked.
chart.on('linkclick',    event => console.log(event.data)); // event.data: ChordChartLinkEvent
// Emitted when the pointer enters a ribbon.
chart.on('linkenter',    event => console.log(event.data)); // event.data: ChordChartLinkEvent
// Emitted when the pointer leaves a ribbon.
chart.on('linkleave',    event => console.log(event.data)); // event.data: ChordChartLinkEvent