Source: https://cards.flixlix.com/energy-breakdown-card/configuration

Energy Breakdown Card

# Configuration

Every option, what it does, and how to use it. Required fields are marked with \*.

In a hurry?

The [Examples](https://cards.flixlix.com/energy-breakdown-card/examples) page has minimal configs you can paste straight into your dashboard. Come back here to fine-tune.

## Card options

Top-level card configuration — type, chart variant, title, and the entities list.

```yaml
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` (string, required): `custom:energy-breakdown-card`
- `entities` (array, required): List of energy sources to display. Each item is documented in the [Entity options](https://cards.flixlix.com/energy-breakdown-card/configuration#entity-options) section.
- `chart_type` (string, default `bar`): Visual variant. One of `bar` (stacked progress bar) or `donut` (ring chart).
- `title` (string): 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.

```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_legend` (boolean, default `true`): Show the legend with names and values.
- `legend_position` (string, default `bottom`): Where to place the legend. One of `bottom` or `right`. Donut only — bar chart always renders the legend below.
- `show_tooltip` (boolean, default `true`): Show a tooltip on hover/tap of a segment.
- `show_total` (boolean, default `true`): Show the total in the center of the donut, or above the bar.
- `show_legend_value` (boolean, default `true`): Show the formatted value in each legend row.
- `show_legend_percentage` (boolean, default `true`): Show the percentage in each legend row.
- `show_icons` (boolean, default `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.

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

- `sort` (boolean, default `true`): Sort segments by value, descending.
- `max_items` (number): Show only the top N largest sources. Leave unset to show all entities.
- `group_others` (boolean, default `true`): When `max_items` is set, bundle the remaining entities into a single _Other_ segment. Set to `false` to drop them entirely.
- `decimals` (number): Default decimals for formatted values. Auto-scaled by magnitude when unset.
- `unit_of_measurement` (string): 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.

```yaml
chart_type: bar
bar_thickness: 24
section_radius: 12
```

- `donut_thickness` (number, default `22`): Donut ring thickness in px (donut only).
- `bar_thickness` (number, default `18`): Bar height in px (bar only).
- `section_radius` (number, default `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>`.

```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_selection` (boolean, default `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_key` (string): 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_.

```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` (string, required): The Home Assistant entity ID.
- `name` (string): Override the entity's friendly name in the legend and tooltip.
- `color` (string): CSS color (HEX, RGB, or `var(...)`). Defaults to a smart palette based on the entity name (solar, grid, battery, …).
- `icon` (string): MDI icon shown next to the entity in the legend.
- `unit_of_measurement` (string): Override the entity's unit of measurement.
- `decimals` (number): Override the number of decimals for this specific entity.
- `multiplier` (number, default `1`): Multiply the raw value (useful to convert Wh → kWh, etc.).
- `tap_action` (object): Action triggered on tap. Defaults to `more-info` for the entity.
- `hold_action` (object): Action triggered on long-press.
- `double_tap_action` (object): 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](https://www.home-assistant.io/dashboards/actions/) 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`.

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

- `tap_action` (object): Triggered on tap/click.
- `hold_action` (object): Triggered on long press.
- `double_tap_action` (object): Triggered on double tap.