Skip to content
D3plus

Chord

Creates a Chord diagram based on a defined set of nodes and links.

Basic example

Section titled “Basic example”

Supplying only links lets the layout infer every node from the source/target ids and draw a ribbon for each directed flow.

const config = {
  links: [
    {source: "alpha", target: "beta"},
    {source: "alpha", target: "gamma"},
    {source: "beta", target: "gamma"},
    {source: "gamma", target: "alpha"},
    {source: "delta", target: "alpha"},
  ],
};

Weighted flows

Section titled “Weighted flows”

Each link’s value sizes its ribbon and the arcs it attaches to, so flows are weighted by magnitude.

The accessor function or key for each link's numeric flow value, which sizes the ribbons and arcs. Defaults to a constant 1, so every link counts equally.

Undirected

Section titled “Undirected”

directed(false) uses the classic d3.chord layout, merging both directions of a pair into a single ribbon — best for symmetric or co-occurrence matrices. Note: an undirected group’s arc size is its outgoing total only (d3.chord’s own convention) — a node with links only ever pointing into it gets a zero-width arc, so give every node at least one outgoing entry.

const config = {
  directed: false,
  value: "value",
  links: [
    {source: "A", target: "B", value: 5},
    {source: "B", target: "A", value: 4},
    {source: "B", target: "C", value: 2},
    {source: "C", target: "A", value: 3},
  ],
};

With arrows

Section titled “With arrows”

arrows adds a d3.ribbonArrow head to the target end of every ribbon, making flow direction explicit. Unlike Network/Sankey, Chord can’t put an arrowhead on the source end alone — arrows("source") is a no-op; use true, "target", or "both".

Toggles directional arrowheads on the ribbons: false, true, "target", "both", or an accessor function. Any of these but false draws each ribbon with a d3.ribbonArrow head on its target end, the only end d3's ribbonArrow can draw; "source" alone draws no arrows.

The pixel size of the ribbon arrowheads. When unset, the size is derived from the arc thickness.

Self loop

Section titled “Self loop”

A link whose source and target are the same node writes to the diagonal of the flow matrix, drawing a ribbon that leaves and re-enters its own arc — useful for a group’s within-group (reflexive) flow alongside its flows to other groups.

const config = {
  value: "value",
  links: [
    {source: "Internal", target: "Internal", value: 12},
    {source: "Internal", target: "External", value: 5},
    {source: "External", target: "Internal", value: 3},
  ],
};

Arc thickness

Section titled “Arc thickness”

arcThickness sets the pixel width of the group arcs (default 20); the ribbons’ inner radius follows automatically, so a thicker band leaves less room for the chords.

const config = {
  arcThickness: 45,
  value: "value",
  links: [
    {source: "alpha", target: "beta", value: 5},
    {source: "alpha", target: "gamma", value: 3},
    {source: "beta", target: "gamma", value: 2},
    {source: "gamma", target: "alpha", value: 4},
  ],
};

Ribbon opacity

Section titled “Ribbon opacity”

chordOpacity sets the fill opacity of every ribbon (default 0.6). Lowering it helps a dense diagram stay readable where many ribbons overlap near the center.

const config = {
  chordOpacity: 0.2,
  value: "value",
  links: [
    {source: "alpha", target: "beta", value: 5},
    {source: "alpha", target: "gamma", value: 4},
    {source: "alpha", target: "delta", value: 3},
    {source: "beta", target: "gamma", value: 6},
    {source: "beta", target: "delta", value: 2},
    {source: "gamma", target: "delta", value: 5},
  ],
};

Group spacing

Section titled “Group spacing”

padAngle sets a fixed radian gap between adjacent group arcs, overriding the automatic gap padPixel (default 2) would otherwise derive from the chart’s radius — useful for a consistent gap across charts of different sizes.

The angular padding, in radians, between adjacent group arcs. When unset, the padding is derived from padPixel.

Custom node identifiers

Section titled “Custom node identifiers”

nodeId points at whatever key identifies a node — here "key" instead of the default "id" — so links can reference nodes by that same value. It only governs matching, though: the drawn label still defaults to reading id, so a custom nodeId needs an explicit label accessor (here d => d.name) alongside it. Supplying nodes explicitly (rather than letting them be inferred from links) also lets a node with no flows at all, like "Operations", still get drawn as an empty arc.

The accessor function or key that gives each node's unique id. Link source/target values are matched against these ids.

Configuration

import {Chord} from "@d3plus/core";

Extends Viz.

activefalse | function

The active callback function for highlighting shapes.

arcThicknessunknownDefault 20

The pixel thickness of the group arcs around the circle.

arrowSizenumber

The pixel size of the ribbon arrowheads. When unset, the size is derived from the arc thickness.

arrowsboolean | "target" | "source" | "both" | functionDefault false

Toggles directional arrowheads on the ribbons: false, true, "target", "both", or an accessor function. Any of these but false draws each ribbon with a d3.ribbonArrow head on its target end, the only end d3's ribbonArrow can draw; "source" alone draws no arrows.

chordOpacityunknownDefault 0.6

The fill opacity of each ribbon (chord).

classNamestring | array.<string> | undefined

CSS classes added to the outermost element this chart or component draws into, next to its fixed d3plus classes, so page CSS can target it: a chart's root <svg class="d3plus-viz"> (its <canvas> with the Canvas renderer) and a standalone component's <svg>. Takes a space-separated string or an array. A new value replaces the classes the previous one added; unset adds none. Tooltips take their own tooltipConfig.className.

colorDefaultscolordefaultsconfig

Overrides the default colors used when assigning fills from data and choosing legible text colors: dark and light (the text colors picked for contrast against a background), missing (null/undefined values), on/off (true/false values), sequential (the anchor hue for magnitude ramps), and scale (the categorical palette, given as a d3 ordinal scale or an array of colors). Keys are merged into the current defaults, and a Viz passes its overrides down to the shapes and components it draws.

configd3plusconfig

Methods that correspond to the key/value pairs and returns this class.

datastring | array.&lt;datapoint&gt; | object

The primary data array used to draw the visualization. The value passed should be an Array of objects or a String representing a filepath or URL to be loaded. The following filetypes are supported: csv, tsv, txt, and json.

If your data URL needs specific headers to be set, an Object with a "url" and "headers" (or any other fetch request option) may also be passed. An Object with any other key is a data row, not a request.

Additionally, a custom formatting function can be passed as a second argument to this method. This custom function will be passed the data that has been loaded, as long as there are no errors. This function should return the final array of obejcts to be used as the primary data array. For example, some JSON APIs return the headers split from the data values to save bandwidth. These would need be joined using a custom formatter.

If you would like to specify certain configuration options based on the yet-to-be-loaded data, you can also return a full config object from the data formatter (including the new data array as a key in the object).

To re-fetch a URL on an interval and redraw when its data changes, set dataPollingInterval; each poll runs the same formatter.

Defaults to an empty array ([]).

directedunknownDefault true

When true (default), uses d3.chordDirected, so each source → target flow is a distinct ribbon colored by its source group. Set to false to use the undirected d3.chord layout, which merges both directions of a pair into a single ribbon (useful for symmetric or co-occurrence data).

facetstring | false | function

Splits the chart into small multiples: a grid of equally sized panels, one per distinct value of this data key or accessor, each drawing the chart for that value's rows. The panels share one legend, color scale, title, and timeline, color each series the same way, and hover, tooltips, and legend clicks apply across all of them. Pass false to draw a single chart. See facetConfig for the grid's layout and shared scales.

facetConfigfacetconfig

Configuration for small multiples (see facet), merged into the current config: - columns / rows: the grid's shape. Chosen by default to make the panels as large as the chart's shape allows. - padding: the space between panels, in pixels (default 20). - sort: panel order — "ascending" (default), "descending", "data" (first appearance), a comparator over facet values, or an Array of values. - scales: "shared" (default) gives every panel of a chart with axes the same x/y domains; "independent" fits each panel to its own rows. Funnel defaults to "independent" (each panel sized to its own widest stage); "shared" sizes every panel against the widest stage across all panels. PolarArea and RadialBar default to "independent" (each panel's rings and ticks fit its own values); "shared" gives every panel the same value domain. - axes: with shared scales, "outer" (default) labels the axes only along the grid's left and bottom edges; "all" labels every panel. An object sets each axis on its own, as in {x: "all", y: "outer"}: every panel labels its x axis, only the left column labels its y axis, and the panels' plot areas line up. BumpChart defaults to "all", and Marimekko labels its categories on every panel and its 0–100% share axis only along the outer edge, even with independent scales. - title: a (value, data) => string function for each panel's title, or false to hide panel titles. - titleConfig: TextBox config for the panel titles (fontSize, fontWeight, fontColor, textAnchor, padding, …).

fontFamilystring | array.&lt;string&gt;

The font family used throughout the visualization.

groupBystring | function | array.&lt;string | function&gt;

Defines the mapping between data and shape. The value can be a String matching a key in each data point (default is "id"), or an accessor Function that returns a unique value for each data point. Additionally, an Array of these values may be provided if the visualization supports nested hierarchies.

highlightfalse | function

Persistently emphasizes the data points matching the given predicate: the matching marks keep their color while every other mark is de-emphasized to a neutral gray (the "emphasis" form — highlight one series, gray the rest). Unlike hover/active (transient, opacity-based), highlight is a standing state that survives pointer movement. Pass false to clear it.

hoverfalse | function

The hover callback function for highlighting shapes on mouseover.

The edges that connect the nodes. The source and target keys in each link (see linksSource/linksTarget) map to node ids. Accepts an Array of data or a String filepath or URL to load; an optional formatting function can be passed as a second argument.

linksSourceunknownDefault "source"

The key used in each link Object to reference the source node's id.

linksTargetunknownDefault "target"

The key used in each link Object to reference the target node's id.

localestring | object

The locale used for all text and number formatting. Supports the locales defined in d3plus-format. The locale can be a complex Object, a locale code (like "en-US"), or a 2-digit language code (like "en"). If a 2-digit code is provided, the "findLocale" function is used to identify the most approximate locale.

noDataMessagebooleanDefault false

Toggles the visibility of the status message that is displayed when no data is supplied to the visualization.

nodeIdstring | functionDefault "id"

The accessor function or key that gives each node's unique id. Link source/target values are matched against these ids.

nodesDataPoint[] | stringDefault "nodes"

The nodes (groups) drawn as arcs around the circle. When omitted, the nodes are inferred from the unique source/target ids in links. Accepts an Array of data or a String filepath or URL to load; an optional formatting function can be passed as a second argument.

onstring

Event listener for the specified event typenames. Mirrors the core d3-selection behavior.

padAnglenumber

The angular padding, in radians, between adjacent group arcs. When unset, the padding is derived from padPixel.

padPixelunknownDefault 2

The approximate pixel gap between adjacent group arcs, converted to an angle from the chart radius. Ignored when padAngle is set.

parentunknown

Parent config used by the wrapper.

renderfunction

Draws the visualization given the specified configuration.

rendererboolean | "svg" | "canvas"

Selects which @d3plus/render backend paints the visible output. "svg" = SvgRenderer (default), "canvas" = CanvasRenderer. Boolean arguments both normalize to "svg".

selectstring | htmlelement

The SVG container element as a d3 selector or DOM element. Defaults to undefined.

shapeConfigd3plusconfigDefault {Path: {label: false}}

Configuration object with key/value pairs applied as method calls on each shape.

thresholdnumber | function

The threshold value for bucketing small data points together, as a share of the total. On a stacked Plot, the series whose summed value across every position is under that share of the whole chart's total merge into one series, stacked on top. A bucket needs at least two items, and its tooltips list them. Off (0) by default on Plot charts.

thresholdKeystring | function

Accessor for the value used in the threshold algorithm. A stacked Plot defaults to its stacked value.

timestring | false | function

Accessor function or string key for the time dimension of each data point.

timelineDefaultstring | date | array.&lt;string | date&gt;

The starting time or range for the timeline. Can be a single Date/String, or an Array of 2 values representing the min and max.

tooltipConfigtooltipconfig

Configuration for the tooltip component.

totalstring | boolean | function

Accessor function or string key for the total value displayed in the visualization.

translatefunction

Defines how informational text strings should be displayed. By default, this function will try to find the string in question (which is the first argument provided to this function) inside of an internally managed translation Object. If you'd like to override to use custom text, simply pass this method your own custom formatting function.

valuestring | functionDefault 1

The accessor function or key for each link's numeric flow value, which sizes the ribbons and arcs. Defaults to a constant 1, so every link counts equally.