type: custom:energy-breakdown-card
title: Energy Breakdown
chart_type: donut
entities:
  - entity: sensor.solar_energy_today
  - entity: sensor.grid_energy_today
  - entity: sensor.battery_energy_today

type*stringrequired

custom:energy-breakdown-card

entities*arrayrequired

List of energy sources to display. Each item is documented in the Entity options section.

chart_typestringdefault bar

Visual variant. One of bar (stacked progress bar) or donut (ring chart).

titlestring

Optional card title shown above the chart.

Legend & tooltip

Toggle and position the legend, tooltip, total, and icons.

Desktop: hovering a segment opens a tooltip near the cursor that tracks the cursor and disappears on leave.

Mobile: tapping a segment opens the tooltip and pins it; tapping the same segment again fires its tap_action (or more-info); tapping outside dismisses it.

example.yaml

chart_type: donut
show_legend: true
legend_position: right
show_tooltip: true
show_total: true
show_legend_value: true
show_legend_percentage: true
show_icons: true

show_legendbooleandefault true

Show the legend with names and values.

legend_positionstringdefault bottom

Where to place the legend. One of bottom or right. Donut only — bar chart always renders the legend below.

show_totalbooleandefault true

Show the total in the center of the donut, or above the bar.

show_legend_valuebooleandefault true

Show the formatted value in each legend row.

show_legend_percentagebooleandefault true

Show the percentage in each legend row.

show_iconsbooleandefault true

Show entity icons next to legend rows.

Data shaping

Sort, group, and format the values that feed the chart.

Use max_items together with group_others to keep the chart readable when you have many low-magnitude sources.

example.yaml

sort: true
max_items: 5
group_others: true
decimals: 1
unit_of_measurement: kWh

sortbooleandefault true

Sort segments by value, descending.

max_itemsnumber

Show only the top N largest sources. Leave unset to show all entities.

group_othersbooleandefault true

When max_items is set, bundle the remaining entities into a single Other segment. Set to false to drop them entirely.

decimalsnumber

Default decimals for formatted values. Auto-scaled by magnitude when unset.

unit_of_measurementstring

Fallback unit for entities that do not expose a unit attribute.

Chart appearance

Tune the visual proportions of each chart variant.

donut_thickness applies only to chart_type: donut; bar_thickness only to chart_type: bar. section_radius works on both.

example.yaml

chart_type: bar
bar_thickness: 24
section_radius: 12

donut_thicknessnumberdefault 22

Donut ring thickness in px (donut only).

bar_thicknessnumberdefault 18

Bar height in px (bar only).

section_radiusnumberdefault thickness/2

Corner radius for sections. On donut, capped to half the ring thickness; on bar, treated as a pixel radius.

Energy dashboard sync

Optionally bind the card to the Home Assistant energy dashboard, so values follow the dashboard's selected date range.

With energy_date_selection: true, the card pulls statistics growth for each entity over the selected period (today, week, custom range) instead of using the entity's current state.

Each Home Assistant energy dashboard exposes its own collection. By default the card binds to the active dashboard's collection. Set collection_key to follow a specific dashboard — keys follow the pattern energy_<dashboard_url>.

example.yaml

type: custom:energy-breakdown-card
energy_date_selection: true
collection_key: energy_living_room
entities:
  - entity: sensor.solar_energy
  - entity: sensor.grid_energy
  - entity: sensor.battery_energy

energy_date_selectionbooleandefault false

When true, values come from the energy dashboard's selected date range (statistics growth). When false, the entity's current state is used directly.

collection_keystring

Bind this card to a specific Home Assistant energy collection (e.g. energy_living_room). Useful when multiple energy dashboards exist. Defaults to the active dashboard's collection.

Entity options

Each item in the entities array supports the options below.

If you only specify entity, the card pulls the friendly name, unit, and icon from Home Assistant and assigns a color from a built-in palette that recognizes common names like solar, grid, and battery.

example.yaml

entities:
  - entity: sensor.solar_energy_today
    name: Solar
    color: "var(--energy-solar-color)"
    icon: mdi:solar-power
  - entity: sensor.grid_energy_today
    name: Grid
    color: "#488fc2"
  - entity: sensor.battery_energy_today
    name: Battery
    icon: mdi:home-battery
    multiplier: 0.001 # Wh -> kWh

entity*stringrequired

The Home Assistant entity ID.

namestring

Override the entity's friendly name in the legend and tooltip.

colorstring

CSS color (HEX, RGB, or var(...)). Defaults to a smart palette based on the entity name (solar, grid, battery, …).

iconstring

MDI icon shown next to the entity in the legend.

unit_of_measurementstring

Override the entity's unit of measurement.

decimalsnumber

Override the number of decimals for this specific entity.

multipliernumberdefault 1

Multiply the raw value (useful to convert Wh → kWh, etc.).

tap_actionobject

Action triggered on tap. Defaults to more-info for the entity.

hold_actionobject

Action triggered on long-press.

double_tap_actionobject

Action triggered on double-tap.

Actions

Per-entity click handlers. Use these to open more-info, navigate, call services, or fire scripts.

Each entity supports the standard Home Assistant action objects. The default tap_action opens the entity's more-info dialog.

On touch devices, the first tap on a segment opens the tooltip. The second tap on the same segment fires its tap_action.

example.yaml

entities:
  - entity: sensor.solar_energy_today
    tap_action:
      action: navigate
      navigation_path: /lovelace/energy
    hold_action:
      action: more-info

tap_actionobject

Triggered on tap/click.

hold_actionobject

Triggered on long press.

double_tap_actionobject

Triggered on double tap.