Skip to content
On this page


29,630 black0k5k10k15k20k25k20,230 blond0k5k10k15k20k40,290 brown0k5k10k15k20k25k30k35k40k9,850 red0k5k11,975 black → black5,871 black → blond 1,951 blond → black8,916 black → brown 8,010 brown → black2,868 black → red 1,013 red → black10,048 blond → blond16,145 brown → blond 2,060 blond → brown6,171 blond → red 990 red → blond8,090 brown → brown8,045 brown → red 940 red → brown6,907 red → redFork ↗︎

Chord diagrams visualize flow between a set of nodes in a graph, such as transition probabilities between finite states. The diagram above shows a fake dataset from Circos of people who dyed their hair.

D3’s chord layout represents flow using a square matrix of size n×n, where n is the number of nodes in the graph. Each value matrix[i][j] represents the flow from the ith node to the jth node. (Each number matrix[i][j] must be nonnegative, though it can be zero if there is no flow from node i to node j.)

Above, each row and column represents a hair color (black, blond, brown, red); each value represents a number of people who dyed their hair from one color to another color. For example, 5,871 people had black hair and dyed it blond, while 1,951 people had blond hair and dyed it black. The matrix diagonal represents people who kept the same color.

const matrix = [
  // to black, blond, brown, red
  [11975,  5871, 8916, 2868], // from black
  [ 1951, 10048, 2060, 6171], // from blond
  [ 8010, 16145, 8090, 8045], // from brown
  [ 1013,   990,  940, 6907]  // from red

A chord diagram visualizes these transitions by arranging the population by starting color along the circumference of a circle and drawing ribbons between each color. The starting and ending width of the ribbon is proportional to the number of people that had the respective starting and ending color. The color of the ribbon, arbitrarily, is the color with the larger of the two values.

See one of:

  • Chords - a layout for chord diagrams
  • Ribbons - a shape primitive for chord diagrams