# ha-sankey-chart draws flow between Home Assistant entities

> ha-sankey-chart is a Home Assistant Lovelace card that renders a Sankey diagram from entities with numeric state, aimed at visualising how energy, water or power flows through a home. It is deliberately narrow, not a general graph card, and its sizing options are where most of the tuning happens.

**MindFreeze/ha-sankey-chart** — A Home Assistant lovelace card to display a sankey chart. For example for power consumption

- Repository: https://github.com/MindFreeze/ha-sankey-chart
- Stars: 679 · Forks: 36
- Language: TypeScript
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/mindfreeze-ha-sankey-chart

## A flow diagram for numeric states, not a general graph card

The card does one thing and says so in the first line of its own description. It is a Home Assistant Lovelace card that displays a sankey chart, for example for energy, power or water consumption, and the readme adds a deliberate warning: it is intended to display connections between entities with numeric state and is not a general graph card. That single sentence tells you what the project is not trying to be, which is useful, because a Sankey diagram in a dashboard can be read in two different ways. One reading is a flow of quantity, where a link's thickness is proportional to a measured value, and the other is a topology map of relationships. This card only does the first. So a value coming out of a solar inverter and a value arriving at a heat pump can be linked with a thickness that reflects the measurement, but arbitrary graph edges with no numeric meaning are outside its model. The topics on the repository point the same way, listing energy-consumption, home-assistant and lovelace-card, and the author field names Ian Richardson.

## The card is configured entirely in YAML, starting with a type key

Installation runs through HACS, and after that the card is added to a dashboard as a custom card. The configuration is YAML, and the first key is the card type, which the options table lists as custom:sankey-chart. From there the two mandatory pieces of structure are nodes, a list of entities or nodes to display, and links, the connections between those nodes. Both are described as objects in their own right further down the documentation, and the nodes list is required unless you use the autoconfig option, which the table marks as experimental. The remaining options are the tuning surface, and they are unusually fine grained for a dashboard card. You control the layout, whether entity icons, names, states and units are shown, the thickness of the coloured bar on each entity box, the gap between a box and where its connection curve starts, the minimum space between boxes in a section, the minimum size of a box, the card height in pixels, and a throttle in milliseconds that limits how often the card re-renders. The throttle option pairs with the sorting behaviour, since the readme notes that if your values change often you may want it to limit update frequency.

## Layout flips to vertical when the dashboard gets narrow

The layout option takes horizontal, vertical or auto, and auto is the default. The horizontal layout flows left to right and vertical flows top to bottom, so the same nodes and links read in either direction. The auto mode is the interesting part and it is defined precisely. The card flips to vertical when the available width is smaller than the sum of all the sections' min_width, and the default min_width is 150 per section. That gives a predictable rule rather than a heuristic: with three sections you need a little over 450 pixels before the card stays horizontal, and on a narrow phone dashboard or a narrow sidebar view it will rotate instead. The height option only matters in horizontal layout, because vertical layout height is dynamic based on content. The sections option carries section-level configuration, including sorting and min_width, which is what lets you override the per-section width used by the auto layout decision. Sections are also where sort_by can be overridden with none to keep a top-level ordering from taking effect, and sort_dir accepts asc for smallest first or desc for biggest first, with desc as the default.

## Scaling has two modes, and one of them silently overrides the other

How box sizes are proportional to values is where the card has a subtlety worth reading twice. The static_scale option sets the state value that corresponds to the maximum size of the card, meaning the height in horizontal layout and the width in vertical. If static_scale is 1000, a box with a state of 500 takes up half of its section. The catch is stated plainly: if some section exceeds the value of static_scale, the card dynamically rescales, overriding the option. So a fixed scale is not a guarantee, it is a request that a single oversized section can cancel. That behaviour is documented with a reference to issue 153, which suggests it was raised as a question rather than designed as a surprise. The sizing model is otherwise simple, with no separate option to weight a section by how many links it carries. The min_state option is a filter rather than a scale: any entity below the value is not displayed, and only positive numbers above 0 are allowed, with the default behaviour of showing everything above 0. There is a documented edge case with round, which rounds the value to at most N decimal places but may not apply to near zero values, tracked as issue 29.

## Hooking into the Energy Dashboard without giving up manual control

Two option groups tie the card to Home Assistant's own energy tooling, and both come with a caveat about what you still have to do. The energy_date_selection option integrates with the Energy Dashboard by filtering data based on a sibling energy-date-selection card, and the readme says explicitly that you still need to declare your entities and links, because the card only takes the date range from the sibling card. It is meant for accumulated sensors, meaning energy, water or gas, and it is not compatible with the time_period options. The time_period_from and time_period_to options take a start and end for a custom period, with values such as now-1d or now/d, and they are the other half of the same incompatibility. The second group is unit conversion. The convert_units_to option turns electricity in kWh or gas in ft3 into energy in MJ, cost in monetary terms, or carbon in gCO2. Cost conversion requires you to also set electricity_price or gas_price and the monetary_unit, and the readme is upfront that automatic conversion does not support varying electricity prices the way the Energy Dashboard does. Carbon conversion multiplies kWh values by a varying grid CO2 intensity using a co2_intensity_entity, whose default is sensor.co2_signal_co2_intensity, and gas has its own gas_co2_intensity whose default depends on locale.

## One registry to watch, and a card that follows a release train

The package manifest describes a small TypeScript project with a conventional build. The runtime dependencies are custom-card-helpers, date-fns and lit 2.8, with lit as the element base, which is the standard approach for Lovelace cards. The build is Rollup with Babel and TypeScript, and the scripts section is short:

```json
  "scripts": {
    "start": "rollup -c rollup.config.dev.js --watch",
    "build": "npm run lint && npm run rollup",
    "lint": "eslint src/*.ts",
    "rollup": "rollup -c",
    "test": "jest"
  }
```

The build runs the linter before the bundler, the tests run under jest with a jsdom environment, and the source lives in src with tests in __tests__. The release process is automated too, through release-please-config.json and a .release-please-manifest.json that records the version, with a CHANGELOG.md and a MIGRATION.md in the repository, which is the file to read if you are upgrading across a major version. The HACS integration has a hacs.json of its own. The licence is MIT, and the project is maintained on a fast cadence, with v6.4.2 released on 2026-10-12 and the last push on 2026-10-17, days before the current date. The repository also carries a CLAUDE.md and an editor configuration in .vscode, plus eslint and prettier configuration, which tells you the project expects contributions to arrive formatted and linted.

## Where this card is the wrong choice

The limits are real and mostly come from the design constraint the readme states up front. Because the card renders connections between entities with numeric state, it cannot show a graph with no measured quantity behind it, so a topology view of your devices, their dependencies or their wiring is out of scope. The autoconfig path, which would generate nodes and links automatically, is marked experimental in the options table, so an adopter who wants zero configuration is relying on the least settled part of the project. The energy date integration has an explicit exclusion with time_period, so you cannot combine a sibling energy-date-selection card with a custom period. Unit conversion into cost is limited in a way that matters for anyone with a variable tariff, since automatic conversion does not support varying electricity prices. The cost of the fine grained layout options is that a first configuration is a long YAML block, and the min_width default of 150 per section means a chart with many sections will flip to vertical on any reasonably narrow view. For a small number of entities a native Home Assistant card may read more clearly than a flow diagram, since a Sankey chart with two nodes is a rectangle.

## Conclusion

ha-sankey-chart fits a Home Assistant user who already has numeric sensors and wants to see where power or water goes, and who is willing to declare entities and links by hand in YAML. It is the wrong tool if you want a general purpose graph, a topology map, or a chart that can be generated from a template sensor without configuration. Verify first that your sensors report numeric states in the unit you intend to plot, that the layout option behaves at your dashboard width, and that the min_state threshold is not hiding the small flows you wanted to see. The last push was on 2026-10-17 and the newest release is v6.4.2 from 2026-10-12, so the HACS installation is on a current version.

## FAQ

### How do I install ha-sankey-chart in Home Assistant?

Install it through HACS. After that you add it to a dashboard as a custom card with the type set to custom:sankey-chart, and declare your nodes and links in YAML.

### What is the difference between horizontal and vertical layout in ha-sankey-chart?

Horizontal flows left to right and vertical flows top to bottom. The default auto layout flips to vertical when the available width is smaller than the sum of all sections' min_width, which defaults to 150 per section.

### Can ha-sankey-chart show costs or carbon emissions?

Yes, through the convert_units_to option, which converts electricity in kWh or gas in ft3 into energy, cost or carbon. Cost conversion needs electricity_price or gas_price plus monetary_unit, and it does not support varying electricity prices.

### What does static_scale do in ha-sankey-chart?

It sets the state value that corresponds to the maximum size of the card, so a static_scale of 1000 makes a box with state 500 fill half of its section. If any section exceeds that value, the card rescales dynamically and overrides the option.

### Does ha-sankey-chart work with the Home Assistant Energy Dashboard?

The energy_date_selection option filters data using the date range from a sibling energy-date-selection card, and is meant for accumulated energy, water or gas sensors. You still have to declare your entities and links, and it is not compatible with the time_period options.

## Sources

- [Issues](https://github.com/MindFreeze/ha-sankey-chart/issues)
- [License: MIT](https://github.com/MindFreeze/ha-sankey-chart/blob/master/LICENSE)
- [MindFreeze/ha-sankey-chart on GitHub](https://github.com/MindFreeze/ha-sankey-chart)
- [README](https://github.com/MindFreeze/ha-sankey-chart/blob/master/README.md)
- [Releases](https://github.com/MindFreeze/ha-sankey-chart/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mindfreeze-ha-sankey-chart