Sankey

Overview

The sankey trace type is used to create Sankey diagrams, which visualize the flow of quantities between different nodes (or categories). Sankey diagrams are commonly used to show the transfer of resources or values, with the width of the flow lines being proportional to the size of the flow.

You can customize the colors, labels, and flow paths to represent your data and flows effectively.

Common Uses

• Flow of Resources: Visualizing how resources (e.g., money, energy, or materials) move between stages.
• Part-to-Part Relationships: Displaying how parts contribute to other parts rather than the whole.
• Energy or Supply Chains: Showing energy transfers or supply chain processes.

Check out the Attributes for the full set of configuration options

Examples

Common Configurations

Simple Sankey DiagramSankey Diagram with Custom ColorsSankey Diagram with Hover Information

Here's a simple sankey diagram showing how values flow between different categories:

You can copy this code below to create this chart in your project:

models:
  - name: sankey-data
    args:
      - echo
      - |
        source,target,value
        0,1,10
        0,2,5
        1,3,15
        2,3,5
traces:
  - name: Simple Sankey Diagram
    model: ${ref(sankey-data)}
    props:
      type: sankey
      node:
        label: ["A", "B", "C", "D"]
      link:
        source: ?{source}
        target: ?{target}
        value: ?{value}
charts:
  - name: Simple Sankey Diagram
    traces:
      - ${ref(Simple Sankey Diagram)}
    layout:
      title:
        text: Simple Sankey Diagram<br><sub>Flow of Resources Between Nodes</sub>

This example demonstrates a sankey diagram with custom node and link colors:

Here's the code:

models:
  - name: sankey-data-colors
    args:
      - echo
      - |
        source,target,value,color
        0,1,10,#1f77b4
        0,2,5,#ff7f0e
        1,3,15,#2ca02c
        2,3,5,#d62728
traces:
  - name: Sankey Diagram with Custom Colors
    model: ${ref(sankey-data-colors)}
    props:
      type: sankey
      node:
        label: ["X", "Y", "Z", "W"]
        color: ?{color}
      link:
        source: ?{source}
        target: ?{target}
        value: ?{value}
charts:
  - name: Sankey Diagram with Custom Colors
    traces:
      - ${ref(Sankey Diagram with Custom Colors)}
    layout:
      title:
        text: Sankey Diagram with Custom Colors<br><sub>Custom Colors for Nodes and Links</sub>

This example shows a sankey diagram where hover information displays both the value and the source-target relationship:

Here's the code:

models:
  - name: sankey-data-hover
    args:
      - echo
      - |
        source,target,value
        0,1,20
        0,2,10
        1,3,15
        2,3,5
traces:
  - name: Sankey Diagram with Hover Information
    model: ${ref(sankey-data-hover)}
    props:
      type: sankey
      node:
        label: ["P", "Q", "R", "S"]
      link:
        source: ?{source}
        target: ?{target}
        value: ?{value}
        hoverinfo: "source+target+value"
charts:
  - name: Sankey Diagram with Hover Information
    traces:
      - ${ref(Sankey Diagram with Hover Information)}
    layout:
      title:
        text: Sankey Diagram with Hover Information<br><sub>Hover Info Displaying Value and Relationships</sub>

A schema to validate plotly trace properties

Attributes

These attributes apply to traces where trace.props.type is set to sankey. You would configure these attributes on the trace with the trace.props object.

arrangement: any
customdata: array
customdatasrc: 'string' #(1)!
domain:
  column: integer
  row: integer
  x: array
  y: array
hoverinfo: any
hoverlabel:
  align: array
  alignsrc: 'string' #(2)!
  bgcolor: array
  bgcolorsrc: 'string' #(3)!
  bordercolor: array
  bordercolorsrc: 'string' #(4)!
  font:
    color: array
    colorsrc: 'string' #(5)!
    family: 'string | array' #(6)!
    familysrc: 'string' #(7)!
    lineposition: array
    linepositionsrc: 'string' #(8)!
    shadow: 'string | array' #(9)!
    shadowsrc: 'string' #(10)!
    size: array
    sizesrc: 'string' #(11)!
    style: array
    stylesrc: 'string' #(12)!
    textcase: array
    textcasesrc: 'string' #(13)!
    variant: array
    variantsrc: 'string' #(14)!
    weight: array
    weightsrc: 'string' #(15)!
  namelength: array
  namelengthsrc: 'string' #(16)!
ids: array
idssrc: 'string' #(17)!
legend: string
legendgrouptitle:
  font:
    color: any
    family: 'string' #(18)!
    lineposition: any
    shadow: 'string' #(19)!
    size: number
    style: any
    textcase: any
    variant: any
    weight: integer
  text: 'string' #(20)!
legendrank: number
legendwidth: number
link:
  arrowlen: number
  color: array
  colorscales: array
  colorsrc: 'string' #(21)!
  customdata: array
  customdatasrc: 'string' #(22)!
  hovercolor: array
  hovercolorsrc: 'string' #(23)!
  hoverinfo: any
  hoverlabel:
    align: array
    alignsrc: 'string' #(24)!
    bgcolor: array
    bgcolorsrc: 'string' #(25)!
    bordercolor: array
    bordercolorsrc: 'string' #(26)!
    font:
      color: array
      colorsrc: 'string' #(27)!
      family: 'string | array' #(28)!
      familysrc: 'string' #(29)!
      lineposition: array
      linepositionsrc: 'string' #(30)!
      shadow: 'string | array' #(31)!
      shadowsrc: 'string' #(32)!
      size: array
      sizesrc: 'string' #(33)!
      style: array
      stylesrc: 'string' #(34)!
      textcase: array
      textcasesrc: 'string' #(35)!
      variant: array
      variantsrc: 'string' #(36)!
      weight: array
      weightsrc: 'string' #(37)!
    namelength: array
    namelengthsrc: 'string' #(38)!
  hovertemplate: 'string | array' #(39)!
  hovertemplatesrc: 'string' #(40)!
  label: array
  labelsrc: 'string' #(41)!
  line:
    color: array
    colorsrc: 'string' #(42)!
    width: array
    widthsrc: 'string' #(43)!
  source: array
  sourcesrc: 'string' #(44)!
  target: array
  targetsrc: 'string' #(45)!
  value: array
  valuesrc: 'string' #(46)!
metasrc: 'string' #(47)!
name: 'string' #(48)!
node:
  align: any
  color: array
  colorsrc: 'string' #(49)!
  customdata: array
  customdatasrc: 'string' #(50)!
  groups: array
  hoverinfo: any
  hoverlabel:
    align: array
    alignsrc: 'string' #(51)!
    bgcolor: array
    bgcolorsrc: 'string' #(52)!
    bordercolor: array
    bordercolorsrc: 'string' #(53)!
    font:
      color: array
      colorsrc: 'string' #(54)!
      family: 'string | array' #(55)!
      familysrc: 'string' #(56)!
      lineposition: array
      linepositionsrc: 'string' #(57)!
      shadow: 'string | array' #(58)!
      shadowsrc: 'string' #(59)!
      size: array
      sizesrc: 'string' #(60)!
      style: array
      stylesrc: 'string' #(61)!
      textcase: array
      textcasesrc: 'string' #(62)!
      variant: array
      variantsrc: 'string' #(63)!
      weight: array
      weightsrc: 'string' #(64)!
    namelength: array
    namelengthsrc: 'string' #(65)!
  hovertemplate: 'string | array' #(66)!
  hovertemplatesrc: 'string' #(67)!
  label: array
  labelsrc: 'string' #(68)!
  line:
    color: array
    colorsrc: 'string' #(69)!
    width: array
    widthsrc: 'string' #(70)!
  pad: number
  thickness: number
  x: array
  xsrc: 'string' #(71)!
  y: array
  ysrc: 'string' #(72)!
orientation: any
stream:
  maxpoints: number
  token: 'string' #(73)!
textfont:
  color: any
  family: 'string' #(74)!
  lineposition: any
  shadow: 'string' #(75)!
  size: number
  style: any
  textcase: any
  variant: any
  weight: integer
type: sankey
uid: 'string' #(76)!
valueformat: 'string' #(77)!
valuesuffix: 'string' #(78)!
visible: any

1. Sets the source reference on Chart Studio Cloud for customdata.
2. Sets the source reference on Chart Studio Cloud for align.
3. Sets the source reference on Chart Studio Cloud for bgcolor.
4. Sets the source reference on Chart Studio Cloud for bordercolor.
5. Sets the source reference on Chart Studio Cloud for color.
6. HTML font family - the typeface that will be applied by the web browser. The web browser can only apply a font if it is available on the system where it runs. Provide multiple font families, separated by commas, to indicate the order in which to apply fonts if they aren't available.
7. Sets the source reference on Chart Studio Cloud for family.
8. Sets the source reference on Chart Studio Cloud for lineposition.
9. Sets the shape and color of the shadow behind text. auto places minimal shadow and applies contrast text font color. See https://developer.mozilla.org/en-US/docs/Web/CSS/text-shadow for additional options.
10. Sets the source reference on Chart Studio Cloud for shadow.
11. Sets the source reference on Chart Studio Cloud for size.
12. Sets the source reference on Chart Studio Cloud for style.
13. Sets the source reference on Chart Studio Cloud for textcase.
14. Sets the source reference on Chart Studio Cloud for variant.
15. Sets the source reference on Chart Studio Cloud for weight.
16. Sets the source reference on Chart Studio Cloud for namelength.
17. Sets the source reference on Chart Studio Cloud for ids.
18. HTML font family - the typeface that will be applied by the web browser. The web browser can only apply a font if it is available on the system where it runs. Provide multiple font families, separated by commas, to indicate the order in which to apply fonts if they aren't available.
19. Sets the shape and color of the shadow behind text. auto places minimal shadow and applies contrast text font color. See https://developer.mozilla.org/en-US/docs/Web/CSS/text-shadow for additional options.
20. Sets the title of the legend group.
21. Sets the source reference on Chart Studio Cloud for color.
22. Sets the source reference on Chart Studio Cloud for customdata.
23. Sets the source reference on Chart Studio Cloud for hovercolor.
24. Sets the source reference on Chart Studio Cloud for align.
25. Sets the source reference on Chart Studio Cloud for bgcolor.
26. Sets the source reference on Chart Studio Cloud for bordercolor.
27. Sets the source reference on Chart Studio Cloud for color.
28. HTML font family - the typeface that will be applied by the web browser. The web browser can only apply a font if it is available on the system where it runs. Provide multiple font families, separated by commas, to indicate the order in which to apply fonts if they aren't available.
29. Sets the source reference on Chart Studio Cloud for family.
30. Sets the source reference on Chart Studio Cloud for lineposition.
31. Sets the shape and color of the shadow behind text. auto places minimal shadow and applies contrast text font color. See https://developer.mozilla.org/en-US/docs/Web/CSS/text-shadow for additional options.
32. Sets the source reference on Chart Studio Cloud for shadow.
33. Sets the source reference on Chart Studio Cloud for size.
34. Sets the source reference on Chart Studio Cloud for style.
35. Sets the source reference on Chart Studio Cloud for textcase.
36. Sets the source reference on Chart Studio Cloud for variant.
37. Sets the source reference on Chart Studio Cloud for weight.
38. Sets the source reference on Chart Studio Cloud for namelength.
39. Template string used for rendering the information that appear on hover box. Note that this will override hoverinfo. Variables are inserted using %{variable}, for example "y: %{y}" as well as %{xother}, {%xother}, {%_xother}, {%xother_}. When showing info for several points, xother will be added to those with different x positions from the first point. An underscore before or after (x|y)other will add a space on that side, only when this field is shown. Numbers are formatted using d3-format's syntax %{variable:d3-format}, for example "Price: %{y:$.2f}". https://github.com/d3/d3-format/tree/v1.4.5#d3-format for details on the formatting syntax. Dates are formatted using d3-time-format's syntax %{variable|d3-time-format}, for example "Day: %{2019-01-01|%A}". https://github.com/d3/d3-time-format/tree/v2.2.3#locale_format for details on the date formatting syntax. The variables available in hovertemplate are the ones emitted as event data described at this link https://plotly.com/javascript/plotlyjs-events/#event-data. Additionally, every attributes that can be specified per-point (the ones that are arrayOk: true) are available. Variables source and target are node objects.Finally, the template string has access to variables value and label. Anything contained in tag <extra> is displayed in the secondary box, for example "{fullData.name}". To hide the secondary box completely, use an empty tag <extra></extra>.
40. Sets the source reference on Chart Studio Cloud for hovertemplate.
41. Sets the source reference on Chart Studio Cloud for label.
42. Sets the source reference on Chart Studio Cloud for color.
43. Sets the source reference on Chart Studio Cloud for width.
44. Sets the source reference on Chart Studio Cloud for source.
45. Sets the source reference on Chart Studio Cloud for target.
46. Sets the source reference on Chart Studio Cloud for value.
47. Sets the source reference on Chart Studio Cloud for meta.
48. Sets the trace name. The trace name appears as the legend item and on hover.
49. Sets the source reference on Chart Studio Cloud for color.
50. Sets the source reference on Chart Studio Cloud for customdata.
51. Sets the source reference on Chart Studio Cloud for align.
52. Sets the source reference on Chart Studio Cloud for bgcolor.
53. Sets the source reference on Chart Studio Cloud for bordercolor.
54. Sets the source reference on Chart Studio Cloud for color.
55. HTML font family - the typeface that will be applied by the web browser. The web browser can only apply a font if it is available on the system where it runs. Provide multiple font families, separated by commas, to indicate the order in which to apply fonts if they aren't available.
56. Sets the source reference on Chart Studio Cloud for family.
57. Sets the source reference on Chart Studio Cloud for lineposition.
58. Sets the shape and color of the shadow behind text. auto places minimal shadow and applies contrast text font color. See https://developer.mozilla.org/en-US/docs/Web/CSS/text-shadow for additional options.
59. Sets the source reference on Chart Studio Cloud for shadow.
60. Sets the source reference on Chart Studio Cloud for size.
61. Sets the source reference on Chart Studio Cloud for style.
62. Sets the source reference on Chart Studio Cloud for textcase.
63. Sets the source reference on Chart Studio Cloud for variant.
64. Sets the source reference on Chart Studio Cloud for weight.
65. Sets the source reference on Chart Studio Cloud for namelength.
66. Template string used for rendering the information that appear on hover box. Note that this will override hoverinfo. Variables are inserted using %{variable}, for example "y: %{y}" as well as %{xother}, {%xother}, {%_xother}, {%xother_}. When showing info for several points, xother will be added to those with different x positions from the first point. An underscore before or after (x|y)other will add a space on that side, only when this field is shown. Numbers are formatted using d3-format's syntax %{variable:d3-format}, for example "Price: %{y:$.2f}". https://github.com/d3/d3-format/tree/v1.4.5#d3-format for details on the formatting syntax. Dates are formatted using d3-time-format's syntax %{variable|d3-time-format}, for example "Day: %{2019-01-01|%A}". https://github.com/d3/d3-time-format/tree/v2.2.3#locale_format for details on the date formatting syntax. The variables available in hovertemplate are the ones emitted as event data described at this link https://plotly.com/javascript/plotlyjs-events/#event-data. Additionally, every attributes that can be specified per-point (the ones that are arrayOk: true) are available. Variables sourceLinks and targetLinks are arrays of link objects.Finally, the template string has access to variables value and label. Anything contained in tag <extra> is displayed in the secondary box, for example "{fullData.name}". To hide the secondary box completely, use an empty tag <extra></extra>.
67. Sets the source reference on Chart Studio Cloud for hovertemplate.
68. Sets the source reference on Chart Studio Cloud for label.
69. Sets the source reference on Chart Studio Cloud for color.
70. Sets the source reference on Chart Studio Cloud for width.
71. Sets the source reference on Chart Studio Cloud for x.
72. Sets the source reference on Chart Studio Cloud for y.
73. The stream id number links a data trace on a plot with a stream. See https://chart-studio.plotly.com/settings for more details.
74. HTML font family - the typeface that will be applied by the web browser. The web browser can only apply a font if it is available on the system where it runs. Provide multiple font families, separated by commas, to indicate the order in which to apply fonts if they aren't available.
75. Sets the shape and color of the shadow behind text. auto places minimal shadow and applies contrast text font color. See https://developer.mozilla.org/en-US/docs/Web/CSS/text-shadow for additional options.
76. Assign an id to this trace, Use this to provide object constancy between traces during animations and transitions.
77. Sets the value formatting rule using d3 formatting mini-languages which are very similar to those in Python. For numbers, see: https://github.com/d3/d3-format/tree/v1.4.5#d3-format.
78. Adds a unit to follow the value in the hover tooltip. Add a space if a separation is necessary from the value.