Options

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

Option	Type	Default	Editor
title	text	none	Title, at the top
style	bar, thin, segmented, tank, ring, needle, arc	bar	Style
entities	list	none	Entities
show	name, value, icon, target, legend toggles	see below	Display
sort	none, ascending, descending	none	Display → Sort
columns	whole number, 1 or more	see below	Display → Columns
animate	true / false	true	Display → Animate

title

An optional header for the card.

title: Batteries

style

Which of the seven styles to draw. Switching style never changes anything else.

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.

Key	Default	Effect
show.name	true	The entity's name
show.value	true	The value, with its unit
show.icon	true	The icon
show.target	true	The target marker, when a target is set
show.legend	false	A key under the card listing the colour bands (see Colour bands)

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. 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 fixes the number per row.

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

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.

Option	Type	Default	Editor
name	text	the entity's friendly name	Entities → row options → Name
icon	icon, such as mdi:lock	the entity's own icon	Entities → row options → Icon
min	number or entity	0	Limits → Minimum
max	number or entity	100	Limits → Maximum
target	number or entity	none	Limits → Target
unit	text	the entity's unit	Display → Unit
decimals	whole number, 0–20 in YAML; the editor offers 0–6	see below	Display → Decimals
severity	list of bands	one band in the theme's primary colour	Colours
tap_action	action	more-info	Actions
hold_action	action	none	Actions
double_tap_action	action	none	Actions

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.

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

Key	Type	Notes
from	number	The lower bound of the band, in the entity's units
color	text	A palette name, any CSS colour or a var(--…)
label	text	Optional. Shown in the legend instead of the generated range

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), and, when sort is ascending or descending, is moved to the end (with none it keeps its listed position). An entity id that does not exist reads "Entity not found".

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.