Sankey Chart Card

A Home Assistant lovelace card to display a sankey chart. For example for energy/power/water consumption.

This card is intended to display connections between entities with numeric state. It is not a general graph card.

Installation

Install through HACS

Options

Nodes object

Links object

Filters

Filters transform a node's raw state before the chart's automatic clamp to ≥ 0. Each entry is a single-key object naming the transform (ESPHome/Plotly style).

Filters apply in order, so [{ multiply: 0.001 }, { offset: -5 }] first scales then offsets.

Pair filters with entity_id to render the negative half of a signed sensor as its own node — the sibling node reads the same entity but applies multiply: -1, so positive readings collapse to 0 (via the chart's positive clamp) and negative readings flow as their absolute value. This is how power-mode autoconfig surfaces grid export and battery charging from a single signed stat_rate.

nodes:
  # Import flow: positive part of the signed sensor (negative readings clamp to 0).
  - id: sensor.grid_power
    section: 0
  # Export flow: flip sign first, then clamp — surfaces only the negative readings.
  - id: sensor.grid_power__export
    entity_id: sensor.grid_power
    filters:
      - multiply: -1
    section: 2

Color ranges

You can color nodes based on their state value by using an object instead of a simple color string:

nodes:
  - id: sensor.temperature
    color:
      red:
        from: 30  # red when >= 30
      orange:
        from: 20
        to: 30    # orange when >= 20 and <= 30
      green:
        to: 20    # green when <= 20

Sections object

Reconcile config

Entity types

• entity - The default value, representing an entity from HA
• passthrough - A visual pass-through box in an intermediate section. Passthroughs are ordinary nodes in the link graph — you connect them with explicit links like any other node. Node ids must be unique, so a passthrough cannot reuse the id of the entity it represents. If you link across a section gap without declaring a passthrough, the card auto-inserts one (or more) in the intermediate sections. V3 configs are migrated on load; v3 passthroughs are renamed to {entity_id}__passthrough_{section} and wired with explicit links. See issue #9. Example — a flow from sensor.parent to sensor.child that passes through a visual box in section 1:

nodes:
  - id: sensor.parent
    section: 0
  - id: child_passthrough
    section: 1
    type: passthrough
  - id: sensor.child
    section: 2
links:
  - source: sensor.parent
    target: child_passthrough
  - source: child_passthrough
    target: sensor.child

• remaining_parent_state - Used for representing the unaccounted state from this entity's parent. Useful for displaying the unmeasured state as "Other". See issue #2 & #28. Only 1 is allowed per group. If you add 2, the state will not be split between them but an error will appear. Obviously it must be listed as a target in some link. Example:

nodes:
  - id: other_consumption  # as long as it is unique
    type: remaining_parent_state
    name: Other

• remaining_child_state - Used for representing the unaccounted state in this entity's children. Like remaining_parent_state but in reverse. Useful for displaying discrepancies where the children add up to more than the parent. See issue #2 & #15. Example:

nodes:
  - id: discrepancy  # as long as it is unique
    type: remaining_child_state
    name: Discrepancy
links:
  - source: discrepancy
    target: sensor.child1
  - source: discrepancy
    target: sensor.child2

• high_carbon_energy / low_carbon_energy - Split an energy flow into its carbon-intensive and low-carbon portions, computed for the selected period via Home Assistant's energy/fossil_energy_consumption API. Requires either energy_date_selection: true or time_period_from so a date range is available, plus a CO2 intensity source — either set co2_intensity_entity explicitly, or rely on auto-discovery from the energy dashboard's configured CO2 Signal entity. The source entities are taken from entity_id (or the node id if it's a real entity) plus any add_entities. See issue #54. Example:

type: custom:sankey-chart
energy_date_selection: true
# co2_intensity_entity: sensor.co2_signal_co2_intensity  # optional — auto-discovered from energy dashboard
nodes:
  - id: grid
    entity_id: sensor.grid_consumption
    section: 0
  - id: low_carbon
    type: low_carbon_energy
    entity_id: sensor.grid_consumption
    name: Low-carbon
    section: 1
  - id: high_carbon
    type: high_carbon_energy
    entity_id: sensor.grid_consumption
    name: High-carbon
    section: 1
links:
  - source: grid
    target: low_carbon
  - source: grid
    target: high_carbon

Autoconfig

This card supports automatic configuration generation based on the HA energy dashboard. It will set default values for some config parameters and populate the nodes and links arrays. This is meant to show energy data and assumes you have configured your Energy Dashboard in HA. Use it like this:

- type: energy-date-selection # you can put this anywhere you want but it is required for energy dashboard integration
- type: custom:sankey-chart
  # ...any other options
  autoconfig:
    print_yaml: false # optional
    # any additional autoconfig options (listed below)

or like this:

- type: custom:sankey-chart
  autoconfig: true
  time_period_from: "now/d" # today

Time Period

The time_period_from and time_period_to options allow you to specify a custom time period for data retrieval. The format is based on Grafana's time range format.

Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks), M (months), y (years)

Note that while seconds and minutes are supported, there is a delay in the statistics data in HA of up to 1 hour, so showing small periods like the last 30 mins probably won't work.

Examples:

• now-5m: 5 minutes ago
• now-1h: 1 hour ago
• now-1d: 1 day ago
• now-1w: 1 week ago
• now-1M: 1 month ago
• now/d: Start of the current day
• now/w: Start of the current week
• now/M: Start of the current month
• now/y: Start of the current year
• now-1d/d: Start of the previous day
• now/d+7h: Today at 07:00
• now-1d/d+23h: Yesterday at 23:00
• now/d-1h: Yesterday at 23:00 (equivalent)

Modifiers can be combined: offsets and roundings are applied left-to-right, so anchors like now/d+7h (round to today's midnight, then add 7 hours) are supported.

If time_period_to is not specified, it defaults to now.

Example configurations:

type: custom:sankey-chart
title: Last 7 days up to the current moment
time_period_from: "now-7d"

type: custom:sankey-chart
title: Yesterday
time_period_from: "now-1d/d"
time_period_to: "now/d"

type: custom:sankey-chart
title: Quiet hours (23:00–07:00)
time_period_from: "now-1d/d+23h"
time_period_to: "now/d+7h"

Examples

Simple

- type: custom:sankey-chart
  show_names: true
  nodes:
    - id: sensor.power
      section: 0
    - id: sensor.washing_machine_power
      section: 1
    - id: sensor.other_power
      section: 1
  links:
    - source: sensor.power
      target: sensor.washing_machine_power
    - source: sensor.power
      target: sensor.other_power

Energy use

- type: custom:sankey-chart
  show_names: true
  unit_prefix: k
  round: 1
  nodes:
    # Section 0 - Sources
    - id: sensor.solar
      section: 0
      color: var(--warning-color)
    - id: sensor.grid
      section: 0
    - id: sensor.battery
      section: 0
      color: var(--success-color)
    # Section 1 - Total
    - id: sensor.total_energy
      section: 1
    # Section 2 - Distribution
    - id: sensor.garage
      section: 2
      color: purple
    - id: sensor.floor1
      section: 2
    - id: sensor.floor2
      section: 2
    # Section 3 - End consumers
    - id: sensor.ev_charger
      section: 3
      tap_action:
        action: toggle
    - id: garage_other
      section: 3
      type: remaining_parent_state
      name: Other
    - id: sensor.living_room
      section: 3
    - id: sensor.washer
      section: 3
  links:
    # Sources -> Total
    - source: sensor.solar
      target: sensor.total_energy
    - source: sensor.grid
      target: sensor.total_energy
    - source: sensor.battery
      target: sensor.total_energy
    # Total -> Distribution
    - source: sensor.total_energy
      target: sensor.floor1
    - source: sensor.total_energy
      target: sensor.floor2
    - source: sensor.total_energy
      target: sensor.garage
    # Distribution -> End consumers
    - source: sensor.garage
      target: sensor.ev_charger
    - source: sensor.garage
      target: garage_other
    - source: sensor.floor1
      target: sensor.living_room
    - source: sensor.floor1
      target: sensor.washer
      value: sensor.washer_energy_net  # connection entity

Reconcile state

Example config where the state of the children must not exceed their parent. reconcile_to: max means to take the bigger of the two values. In other words, if the sum of the children is more than the state of the parent, the parent state will be set to the sum of its children within the card. reconcile_to: min would do the opposite and reduce the state of the children so they fully fit within the parent. latest just takes whichever value was updated last.

- type: custom:sankey-chart
  show_names: true
  nodes:
    - id: sensor.power
      section: 0
      children_sum:
        should_be: equal_or_less
        reconcile_to: max
    - id: sensor.washing_machine_power
      section: 1
    - id: sensor.other_power
      section: 1
  links:
    - source: sensor.power
      target: sensor.washing_machine_power
    - source: sensor.power
      target: sensor.other_power

You can find more examples and help in the HA forum https://community.home-assistant.io/t/anyone-using-the-sankey-chart-card/423125

Energy Dashboard

For automatic configuration from your Energy Dashboard setup, see autoconfig. To bind the chart's date range to an energy-date-selection card while keeping a manual config, see the energy_date_selection option.

FAQ

Q: How do I migrate my config from the old format (v3) to the new format (v4)?

A: See the Migration Guide for step-by-step instructions on converting your configuration.

Q: Do my entities need to be added to the energy dashboard first?

A: This card doesn't know/care if an entity is in the energy dashboard. Unless you use autoconfig because that relies entirely on the energy dashboard.

Q: How do I get total [daily] energy?

A: There isn't a general Consumed Energy sensor in the HA Energy dashboard AFAIK. HA calculates it based on all the in/out kWh values. I can't tell you exactly how to calculate it because it depends on what values you can monitor. Some people already have a Total Consumption sensor, others have a Current Consumption and create an integration sensor from that, etc.

Q: Can I group/sum entities in the chart?

A: The easiest way is to do it with a template sensor in HA. However it can be done in the chart without a new HA entity. If you have an entity with type: remaining_parent_state and it is the only child of its parents, it will just be a sum of all the parents. Similarly if you have an entity with type: remaining_child_state and it is the only parent of all its children, it will be a sum of all the children.

Q: How do I zoom back out after using the zoom action?

A: Tap the same (currently top level) entity again to reset the zoom level.

Q: My (template) sensor doesn't work with energy_date_selection!?

A: Sensors should have a proper state_class in order for statistics to work. Most commonly state_class: total. See https://developers.home-assistant.io/docs/core/entity/sensor/#long-term-statistics

Q: Can you add feature X, so I don't have to create template entities in HA?

A: Most probably no. There is nothing wrong with template entities and they should be the preferred approach instead of duplicating HA functionality in every card. I do make exceptions for often required features like remaining_parent_state but prefer to rely on HA functionality whenever I can.

Q: My entities are not rendered where I expected

A: By default entities are displayed in the order in which they appear in the config. You can rearrange them in the YAML or use the sorting options.

Q: Does the order of links matter, and how should I order them?

A: Yes — but it matters per shared source and per shared target, not globally. The chart walks sections left-to-right, then nodes in nodes[] order, then each node's outgoing links in the order you wrote them. Each link subtracts from the remaining state of both its source and its target, so the first link out of a given source gets first claim on that source's value, and the first link into a given target gets first claim on that target's value. remaining_parent_state / remaining_child_state nodes absorb whatever is left after the earlier links are accounted for. Rule of thumb: for each source, list its outgoing links from highest priority to lowest, with any remaining_* sink last. If reordering to fix one flow keeps breaking another, the conflict usually isn't solvable by ordering alone — split the shared node or set the link's value (entity id) so the flow isn't inferred from "remaining."

Q: The font size is too small sometimes

A: The font size is determined by the available space, so you can increase the minimum font size by increasing min_box_size and/or min_box_distance

Development

1. npm i
2. npm start
3. The compiled .js file will be accessible on http://127.0.0.1:3000/ha-sankey-chart.js.
4. On a running Home Assistant installation add this to your Lovelace resources:

- url: 'http://127.0.0.1:3000/ha-sankey-chart.js'
  type: module