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, line (v1.2.0+)	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
include	rule	none	Entities → Also show every entity that matches
exclude	rule	none	Entities → Leave out
hide_unavailable	true / false	false	Display → Hide unavailable entities
limit	whole number, 1 or more	no limit	Display → Show at most
color_icon	true / false	false	Colours → Colour icons to match their band

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.

Key	Default	Effect
show.name	true	The entity's name
show.value	true	The value, with its unit (an unavailable sensor still shows its status)
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, 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

Key	Matches
label	A label on the entity or on its device
area	The entity's area, or its device's
floor	The floor of that area
device_class	The entity's device class, such as battery or temperature
domain	The part of the entity id before the dot, such as sensor
entity	An entity id (exclude only)

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.

Option	Type	Default	Editor
attribute	attribute name	none (the state)	Entities → row options → Attribute (per entity only)
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	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.

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

Key	Type	Notes
from	number or entity	The lower bound of the band, in the entity's units (an entity from v1.1.0)
color	text	A palette name, any CSS colour or a var(--…)
label	text	Optional. Shown in the legend instead of the generated range
icon	icon	Optional. The icon to show while the value is in this band (v1.1.0+)

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.