Options

Every option Chartdeck understands, with its type, default and where to find it in the visual editor. Options marked per-entity can be set once for the whole card and overridden on a single entity.

A complete example

type: custom:chartdeck-card
title: Batteries
style: bar
entities:
  - entity: sensor.front_door_battery
    name: Front door
    icon: mdi:lock
  - sensor.back_garden_battery
min: 0
max: 100
target: 50
unit: '%'
decimals: 0
severity:
  - from: 0
    color: red
    label: Low
  - from: 20
    color: amber
  - from: 50
    color: green
show:
  name: true
  value: true
  icon: true
  target: true
  legend: false
sort: none
columns: 1
animate: true
tap_action:
  action: more-info
hold_action:
  action: none
double_tap_action:
  action: none

Only type and entities are needed. Everything else has a default.

Card options

title

An optional header for the card.

title: Batteries

style

Which of the styles to draw. Switching style never changes anything else. The line chart (v1.2.0+) has its own options, listed on Line.

style: ring

entities

A list of entities. Each item is either an entity id or an object with entity and any of the per-entity options below.

entities:
  - sensor.back_garden_battery
  - entity: sensor.front_door_battery
    name: Front door

In the editor you add entities with the picker at the bottom of Entities, reorder them with the arrows, and open the chevron on a row to override its options.

show

Switches for what each entity displays. All are on except legend.

show:
  icon: false
  legend: true

sort

none keeps the order you listed. ascending and descending order the entities by how full each one is within its own min to max, which is the same proportion the bar draws. Entities with different units and ranges therefore sort the way they look. Ties keep their listed order. With ascending or descending, entities that are unavailable are moved to the end; with none they keep their listed position.

sort: descending

columns

How many entities sit side by side, at most. Bar, thin and segmented are lists, so the default is one column. Tank, ring, needle and arc sit as many to a row as fit the card’s width; columns sets the number per row. (v1.0.1+)

columns is a maximum: each style needs a minimum width per column (bars 160 px, thin 140, segmented 180, tank 80, ring and arc 128, needle 134), and when the card is too narrow for the number you set, it uses fewer columns rather than squeezing them. Gauges in a very narrow card scale down to fit.

columns: 2

animate

Draws the bars, rings and needles in when the card loads and moves them smoothly when a value changes. Animation is also switched off automatically when your device asks for reduced motion.

animate: false

include and exclude (v1.1.0+)

Fill the card from a rule instead of picking every entity, so new devices appear without editing the dashboard. Entities you list in entities come first; matched ones follow, by name, and take the card’s options.

include:
  area: kitchen
  device_class: [temperature, humidity]
exclude:
  entity: sensor.oven_probe
  label: ignore

Each key takes one value or a list. In include, the values of one key are alternatives and different keys must all match: the example above is “temperature or humidity sensors in the kitchen”. In exclude, an entity is left out if it matches any key.

Only entities with a number to show are matched (plus unavailable and unknown ones), so an area rule doesn’t pull in the room’s lights. Entities hidden in Home Assistant are never matched. The card notices new matches by itself: add a sensor to the area or give it the label, and it appears. A rule that matches nothing reads “No entities match right now.”

hide_unavailable (v1.1.0+)

Leaves out every entity that is unavailable or unknown, listed or matched.

hide_unavailable: true

limit (v1.1.0+)

Shows at most this many entities, counted after sort. With sort: none it keeps the first ones in order.

include:
  device_class: battery
sort: ascending
limit: 5

color_icon (v1.1.0+)

Colours each icon with the colour of the band its value is in, so a battery icon turns red when low. Unavailable entities keep their usual icon colour.

color_icon: true

Per-entity options

These can be written on the card (applying to every entity) or on one entity (applying to just that one). An entity’s own value wins.

At card level the editor shows unit, decimals, min, max, target, severity and the three actions. name and icon are set per entity. Every option in the table works in both places in YAML.

On a single entity, the editor’s Show options chevron reveals Name, Unit, Decimals, Icon, Minimum, Maximum, Target, its own Colours and its own three actions.

attribute (v1.1.0+)

Draws one of the entity’s attributes instead of its state: a thermostat’s current temperature, a weather entity’s humidity, a media player’s volume. Set it per entity.

entities:
  - entity: climate.lounge
    attribute: current_temperature
    unit: °C

The entity’s unit and display precision describe its state, so neither is used for an attribute: set unit yourself, and the decimals default to how the attribute was reported (at most 2) until you set decimals. When the attribute is missing, the card shows the entity’s state, so a media player that is off reads “Off”.

name and icon

entities:
  - entity: sensor.front_door_battery
    name: Front door
    icon: mdi:lock

min, max and target

Each is either a number or the id of another entity, whose current state is used. That lets a gauge follow, for example, a tank’s capacity or a day’s target that you adjust from a helper.

min: 0
max: input_number.tank_capacity
target: 50

In the editor, each of the three has a drop-down with Default, Number and Entity.

• Values outside min to max are clamped for drawing, but the number shown is the real value.
• max must be greater than min.
• When min is below zero and max above it, bars fill from zero (left for negative, right for positive) and the ring, needle and arc are drawn from the zero point.
• If the entity you gave for a limit is unavailable or not a number, the card uses the default for that limit (0 for min, 100 for max, no marker for target) and logs a console warning once.

unit and decimals

unit is shown after the value; leave it out to use the entity’s own unit.

decimals is the number of digits after the decimal point. When you do not set it, Chartdeck uses the display precision you chose for the entity in Home Assistant, or failing that, 0 for % and 1 for anything else.

unit: kW
decimals: 2

severity

The colour bands. See Colour bands for the colours, presets and legend.

severity:
  - from: 0
    color: red
    label: Low
  - from: 20
    color: amber
  - from: 50
    color: green

tap_action, hold_action and double_tap_action

Home Assistant’s standard actions: more-info, navigate, url, perform-action, toggle and none. Tapping an entity opens its more-info dialog unless you change it.

tap_action:
  action: navigate
  navigation_path: /lovelace/energy
hold_action:
  action: more-info
double_tap_action:
  action: none

Unavailable entities

An entity that is unavailable, unknown or not a number draws an empty track with the text “Unavailable” (or Home Assistant’s own wording for its state). When sort is ascending or descending it is moved to the end; with none it keeps its listed position. An entity id that does not exist reads “Entity not found” and shows a placeholder icon.

The status text shows even when show.value is off, so an offline sensor never looks like an empty reading. (v1.0.1+)

Placement

Chartdeck works in masonry and sections dashboards and inside stacks. In a sections view, resize it with the normal handles; the height follows the content.