import { ChordDiagram } from "semiotic"
ChordDiagram shows the flow and magnitude of relationships between entities arranged in a circle. Arcs around the circumference represent nodes, and ribbons connecting them encode the volume of the relationship. Chord diagrams are especially useful when relationships are asymmetric and you want to highlight who sends more to whom.
Quick Start
The simplest chord diagram requires just edges with source, target, and value properties. Nodes are inferred automatically from the edges.
import { ChordDiagram } from "semiotic" const frameProps = { /* --- Data --- */ edges: [ { source: "Engineering", target: "Design", value: 40 }, { source: "Design", target: "Engineering", value: 25 }, { source: "Engineering", target: "Marketing", value: 15 }, // ...more edges with value ] } export default () => { return <ChordDiagram {...frameProps} /> }
Examples
Colored by Category
Provide explicit nodes with a category field and use colorBy to color arcs by group. Use edgeColorBy to control whether chords inherit the source or target color.
import { ChordDiagram } from "semiotic" const frameProps = { /* --- Data --- */ nodes: [ { id: "Engineering", category: "Technical" }, { id: "Design", category: "Technical" }, { id: "Marketing", category: "Business" }, { id: "Sales", category: "Business" }, ], edges: edgeData, /* --- Customize --- */ colorBy: "category", edgeColorBy: "source" } export default () => { return <ChordDiagram {...frameProps} /> }
Wider Groups with Padding
Increase padAngle to add spacing between arcs and groupWidth to make the outer arcs thicker.
import { ChordDiagram } from "semiotic" const frameProps = { /* --- Data --- */ edges: edgeData, /* --- Layout --- */ padAngle: 0.05, groupWidth: 30, /* --- Customize --- */ edgeOpacity: 0.35 } export default () => { return <ChordDiagram {...frameProps} /> }
Website Traffic Flow
Chord diagrams work well for showing page-to-page navigation patterns on a website, where each arc is a page and chords represent user traffic between pages.
import { ChordDiagram } from "semiotic" const frameProps = { /* --- Data --- */ edges: [ { source: "Homepage", target: "Products", value: 500 }, { source: "Homepage", target: "Blog", value: 300 }, { source: "Products", target: "Checkout", value: 200 }, // ...page-to-page traffic flows ], /* --- Layout --- */ padAngle: 0.03, /* --- Customize --- */ colorBy: "id", colorScheme: ["#6366f1", "#22c55e", "#f59e0b", "#ef4444", "#06b6d4"], edgeColorBy: "source", edgeOpacity: 0.4 } export default () => { return <ChordDiagram {...frameProps} /> }
Props
| Prop | Type | Required | Default | Description |
|---|
edges | array | Yes | — | Array of edge objects with source, target, and value properties. |
nodes | array | — | (inferred from edges) | Array of node objects. Will be inferred from edges if not provided. |
sourceAccessor | string | function | — | "source" | Field name or function to access source node identifier. |
targetAccessor | string | function | — | "target" | Field name or function to access target node identifier. |
valueAccessor | string | function | — | "value" | Field name or function to access edge value (width of chord). |
nodeIdAccessor | string | function | — | "id" | Field name or function to access node identifier. |
colorBy | string | function | — | — | Field name or function to determine node color. |
colorScheme | string | array | — | "category10" | Color scheme name or custom colors array. |
edgeColorBy | "source" | "target" | function | — | "source" | Edge color strategy: "source", "target", or a custom function. |
padAngle | number | — | 0.01 | Padding angle between adjacent groups in radians. |
groupWidth | number | — | 20 | Width of the outer arc (node) in pixels. |
sortGroups | function | — | — | Sort function for groups (nodes) around the circle. |
nodeLabel | string | function | — | (uses nodeIdAccessor) | Label accessor for nodes around the circumference. |
showLabels | boolean | — | true | Show labels around the circumference. |
enableHover | boolean | — | true | Enable hover annotations. |
edgeOpacity | number | — | 0.5 | Opacity of the chord ribbons. |
tooltip | object | function | — | — | Tooltip configuration or render function. |
width | number | — | 600 | Chart width in pixels. |
height | number | — | 600 | Chart height in pixels. |
margin | object | — | { top: 50, bottom: 50, left: 50, right: 50 } | Margin around the chart area. |
title | string | — | — | Chart title displayed at the top. |
frameProps | object | — | — | Additional StreamNetworkFrame props for advanced customization. Escape hatch to the full Frame API. |
Graduating to the Frame
When you need more control — custom arc rendering, complex interactions, or advanced chord configuration — graduate to StreamNetworkFrame directly. Every ChordDiagram is just a configured StreamNetworkFrame under the hood.
Chart (simple)
JSX
import { ChordDiagram } from "semiotic" <ChordDiagram edges={flowData} colorBy="category" padAngle={0.05} groupWidth={30} showLabels={true} />
Frame (full control)
JSX
import { StreamNetworkFrame } from "semiotic" <StreamNetworkFrame nodes={nodeData} edges={flowData} nodeIDAccessor="id" sourceAccessor="source" targetAccessor="target" edgeWidthAccessor="value" networkType={{ type: "chord", padAngle: 0.05, groupWidth: 30 }} nodeStyle={(d, i) => ({ fill: colorScale(d.category), stroke: "black" })} edgeStyle={d => ({ fill: colorScale(d.source.category), fillOpacity: 0.5 })} nodeLabels={d => d.id} hoverAnnotation={true} size={[600, 600]} />
The frameProps prop on ChordDiagram lets you pass any StreamNetworkFrame prop without fully graduating:
JSX
// Use frameProps as an escape hatch <ChordDiagram edges={flowData} colorBy="category" frameProps={{ annotations: [ { type: "node", id: "Engineering", label: "Largest dept" } ], customNodeIcon: ({ d }) => ( <rect width={20} height={d.height} fill="steelblue" /> ) }} />
- ForceDirectedGraph — force-directed layout for general network visualization
- SankeyDiagram — linear flow diagram showing magnitude of movement through stages
- TreeDiagram — hierarchical layouts for tree-structured data
- StreamNetworkFrame — the underlying Frame with full control over every rendering detail
- Tooltips — custom tooltip content and positioning