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+), area, column, combined (v1.3.0+), pie, rings, pictograph, waffle, histogram, scatter, bubble, heatmap, box, funnel, waterfall, treemap, sunburst, icicle, radar, polar_area, grouped_bars, bullet, lollipop, slope, dumbbell, range_area, sparkline, streamgraph, candlestick, violin, beeswarm, timeline, climate, sankey, wind_rose, day_clock, trend (v2.0.0+), marimekko, chord, battery, spiral, strip_plot, cycle_plot (v2.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
when	condition	none	Chart → Show every series only while this entity (v2.2.0+)
legend_toggle	true / false	false	Chart → Tap a name to hide or show it (v2.2.0+)
export	true / false	false	Display → Export menu (v2.2.0+)
source: energy	with energy_flows and energy_split	none	Chart → Readings from → Energy dashboard (v2.2.0+)

title

An optional header for the card.

title: Batteries

style

Which of the styles to draw. Switching style never changes anything else. The history charts have their own options, listed on their pages: Line (v1.2.0+), Area, Column and Combined (v1.3.0+). Calendar periods and grouping, shared by all of them, are on the Line page. The parts-of-a-total charts, drawn from current values, have theirs on Pie and donut, Rings, Pictograph and Waffle (v2.0.0+). The distribution charts, also drawn from history, have theirs on Histogram, Scatter, Bubble, Heatmap and Box plot (v2.0.0+). The other 2.0.0 charts have theirs on their own pages: Funnel, Waterfall, Treemap, Sunburst and icicle, Radar, Polar area, Grouped and stacked bars, Bullet, Lollipop, Slope, Dumbbell, Range area, Sparkline, Streamgraph, Candlestick, Violin and raincloud, Beeswarm, State timeline, Climate, Sankey, Wind rose, 24-hour clock, Trend. The v2.2.0 charts have theirs on Marimekko, Chord, Battery grid, Spiral, Strip plot and Cycle plot. Zoom, annotations, value labels, synced charts, small multiples, highest/lowest/average marks and the log scale are line-chart options, on the Line page, as are (v2.2.0+) forecasts, anomalies, earlier spans behind the chart and the now line. For the badge row there is also a Chartdeck badge (v2.2.0+).

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

when (v2.2.0+)

Shows a history chart's series only while another entity is in a state, or above or below a value. Readings outside are gaps, as if the sensor had been unavailable. Set it on the card for every series, or on one entity for just that one.

when:                       # card: every series without its own
  entity: person.sam
  state: home
entities:
  - sensor.living_room_power
  - entity: sensor.flow_temperature
    when:                   # its own wins over the card's
      entity: sensor.heat_pump_power
      above: 50

Key	Type	What it tests
entity	entity id	The entity to watch (needed)
state	a state, a list, or text with commas between (home, work)	It is in one of these states
above	number	Its state is above this number
below	number	Its state is below this number

• Every key that is set must hold: above: 18 with below: 22 is "between 18 and 22". A when with only an entity is ignored.
• An unavailable or unknown condition entity counts as not met. Before its first recorded state, nothing is shown.
• The readings are hidden before they are grouped, so columns, averages, highest and lowest marks, labels and the hover readout all use only the readings that were kept.
• With source: statistics, a statistics row is kept when the condition held at the row's start.
• The chart loads the condition entity's history along with its own and follows its changes live. While that loads the chart says it is loading; if it can't be read, conditional series show nothing (other series draw as usual).
• An entity of its own with a when that is half filled in (no entity yet) doesn't hide the card's. Entities matched by an include rule take the card's when.

It works on the line, area, column, combined, range area, sparkline, streamgraph, beeswarm, violin, histogram, heatmap, dumbbell, slope, trend, waterfall, state timeline, box plot, candlestick, 24-hour clock and wind rose charts. On the 24-hour clock, time on and switch-ons count only the time the condition held; on the wind rose, direction and speed are each hidden by their own condition, and the rose uses only the time both were kept. The climate chart accepts when but doesn't apply it: a thermostat's temperature, set point and heating are one record.

The line and area charts can also draw the hidden readings faintly (when_ghost) and a strip showing when each condition held (when_strip): see Line.

In the editor: each entity's options have Show only while this entity, …is in state (commas between), …is above and …is below. The card's own condition is in the Chart section, under the style's options: Show every series only while this entity and the same three fields.

legend_toggle (v2.2.0+)

Turns the row of names above a chart into switches: tap a name to hide or show that series, hold it to show only that one. What is hidden is remembered per card in the browser. It works on the charts with that row: line, area, column, combined, range area, histogram, streamgraph, box plot and candlestick. See Line.

legend_toggle: true

export (v2.2.0+)

Adds a ⋮ button to the top right of a chart, with a menu to save or copy what it shows.

export: true

Menu item	What it does
Save as PNG	Saves a picture of the card at twice its size on screen
Save as SVG	Saves the card as a vector picture
Copy CSV	Copies the plotted values: timestamp,entity,value,unit, a row per reading drawn
Copy YAML	Copies the card's config

• Everything happens in the browser; nothing is sent anywhere.
• The CSV of a history chart lists the readings it drew, without gaps or the values carried to the edges, and only the series on show. Charts of current values, and the box plot and candlestick, list each entity's current value.
• Where the browser won't let the card use the clipboard (a dashboard served over plain http), the CSV or YAML is saved as a file instead, and the card says so.
• The pictures use the card's own font when Home Assistant serves it; otherwise they fall back to a font of the same kind on the computer opening them.
• The button sits in the title row when the card has a title. Without one it gets a short row of its own above the chart, so the card is a little taller.
• The menu works from the keyboard: arrow keys move, Escape closes.
• It is for the chart styles. The bar and gauge styles ignore it.

In the editor: Export menu in the Display section, for chart styles.

source: energy (v2.2.0+)

Draws the flows set up in Home Assistant's Energy dashboard, without listing any entities. The card reads the dashboard's settings, finds the statistic for each flow, and draws it from long-term statistics.

type: custom:chartdeck-card
style: column
source: energy
energy_flows: [grid_import, grid_export, solar]
energy_split: true

Option	Type	Default	Editor
source	energy	none	Chart → Readings from → Energy dashboard
energy_flows	list of grid_import, grid_export, solar, battery_out, battery_in, gas, water, devices	see below	Chart → Energy flows
energy_split	true / false	true	Chart → Export and battery charging below the axis (column and area)

• Line, column and area draw the flows over time, an hour at a time by default, as how much each meter rose. With no energy_flows they draw grid import and export, solar, and battery out and in. The names row shows each flow's total over the span.
• Column and area draw energy leaving the house (grid export and battery charging) below the axis, as negative values; hover readouts, labels and the header still read it positive. energy_split: false stacks everything upward. See Column.
• Pie and Sankey draw each flow's total over the card's period: see Pie and Sankey. A pie defaults to where the energy came from (grid import, solar, battery out); a Sankey to every electricity flow and the devices, and it refuses gas and water.
• devices draws each individual device from the Energy dashboard as a series of its own.
• Other styles refuse source: energy with a message listing the ones that take it. energy_flows and energy_split need source: energy.
• A flow whose statistic has no entity (an integration's own statistic, or a meter that has been removed) is still drawn, named from the Energy dashboard or the statistic. It has no more-info dialog, and never reads "Entity not found".
• Units come from the statistics; electricity flows are in kWh when a statistic doesn't say.
• Any entities you list are drawn after the energy flows.
• The Energy dashboard's settings are read once per page and again after 30 minutes. While they load the card says "Loading the Energy dashboard settings…"; with none of the chosen flows set up it says "The Energy dashboard has none of these flows set up yet."

Choosing Energy dashboard in the editor sets hourly grouping on line, column and area charts, and today as the period on a pie or Sankey with none set. Choosing another source again removes energy_flows and energy_split.

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; converts between known units (v2.2.0+)	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
transform	cumulative or derivative, with its own keys	none	Entities → row options → Transform (per entity only, v2.2.0+)
when	condition	the card's when	Entities → row options → Show only while this entity (v2.2.0+)

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.
• (v2.2.0+) A limit read from an entity is converted from that entity's own unit to the unit the card shows, when the two are a known pair (see unit conversion). This holds even without unit set: a °C sensor with max from a °F input_number now reads the helper in °C. Before, such a limit was used as it stood, so this only changes cards whose limit was already in the wrong unit. Numbers you type are never converted.

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

Unit conversion (v2.2.0+)

unit converts when it can. When the sensor's own unit and the unit you set are both in one of the families below, the card converts the value, its history, and any limit or colour band start read from another entity. Otherwise unit stays the text shown after the value, as before.

Family	Units
Energy	Wh, kWh, MWh, GWh
Power	W, kW, MW
Temperature	°C, °F, K
Speed	m/s, km/h, mph, kn, ft/s
Pressure	Pa, hPa, mbar, kPa, bar, inHg, mmHg, psi
Length	mm, cm, m, in, ft

entities:
  - entity: sensor.grid_power        # reports W
    unit: kW                         # shown in kW
    max: 5                           # typed numbers are in the shown unit: 5 kW
  - entity: sensor.outside_temperature_f   # reports °F
    unit: °C
  - entity: sensor.wind_speed        # reports m/s
    unit: mph
    max: input_number.gale_speed     # converted from the helper's own unit (km/h) to mph

• Typed numbers are in the shown unit. min, max, target and band from values you type are never converted.
• Entity values are converted from their own unit: a limit, a band start or a line annotation read from an entity, when its unit and the shown unit are a known pair.
• What stays text: a unit the card doesn't know, two units from different families (W and kWh), a sensor with no unit, and an attribute (attributes have no unit), except a thermostat's temperatures on the climate chart, which convert from Home Assistant's unit system.
• Decimals: when you don't set decimals, the entity's display precision is moved by the change of scale (W at 0 decimals shows kW at 3; m/s at 1 shows km/h at 0), between 0 and 6.
• Every style converts: the gauges and bars, the history charts and their history, the wind rose (its default speed bands follow the shown unit) and the climate chart.

In the editor, an entity's Unit becomes a drop-down of the units its sensor converts to, when the sensor's unit is one the card knows; you can still type any text. The card-wide Unit in Display stays a text box.

transform (v2.2.0+)

Turns a series into its running total or its rate of change before it is drawn. Set it per entity, in its options; a card-wide transform does nothing.

Running total: transform: cumulative

entities:
  - entity: sensor.grid_import_meter     # kWh, total_increasing
    transform: cumulative
    transform_reset: billing             # none (default), day, week, month or billing
    transform_reset_day: 15              # for billing: 1 to 28 (default 1)
  - entity: sensor.house_power           # W
    transform: cumulative
    transform_reset: day
    unit: kWh                            # the power integrated into kWh

Key	Values	Default	Editor
transform	cumulative	none	Transform → Running total
transform_reset	none, day, week, month, billing	none	Running total starts again
transform_reset_day	whole number, 1–28	1	Billing day of the month (1–28), shown with billing

• A meter (state class total_increasing) adds up how much it rose, with its resets handled, so the line is the energy used since the start. A total meter adds every change, so it can fall.
• Anything else is added up over time: each reading times how long it held, until the next one (the last one holds until now). A power sensor in W, kW or MW becomes energy in Wh, kWh or MWh. With unit set to an energy unit, the result is scaled to it: a W sensor with unit: kWh reads in kWh. Other units get "·h" (L/min becomes L/min·h).
• The total starts at 0 at the chart's left edge, and drops back to 0 at each reset: midnight, the start of the week or month, or midnight on transform_reset_day of each month for billing. Resets follow the calendar in Home Assistant's time zone. billing with day 1 is the same as month; days stop at 28 so every month has one.
• Gaps stay gaps. A meter's total carries across a gap.
• The names row, hover readout and value axis show the total.

Rate of change: transform: derivative

entities:
  - entity: sensor.heat_pump_energy      # kWh, total_increasing
    transform: derivative
    transform_unit_time: h               # s, min, h (default) or d
    transform_smoothing_time: 15min      # optional: a time window

Key	Values	Default	Editor
transform	derivative	none	Transform → Rate of change
transform_unit_time	s, min, h, d	h	Rate per
transform_smoothing	whole number, 1–100	1 (off)	Smooth over readings
transform_smoothing_time	a time up to 7 days: a number then s, min, h or d (90s, 15min, 1.5h, 1d)	none	Smooth over time (like 15min; used instead of readings)

• The rate at each reading is the change from the reading before, divided by the time between them, drawn at the later reading. kWh per hour reads as kW (Wh per hour as W, MWh per hour as MW); anything else as its unit per time (°C/h, L/min).
• A meter (state class total_increasing): a fall is a reset, so that step is dropped and measuring starts again from the new reading. Other sensors can have a negative rate.
• A gap starts again: no rate is measured across it. The value carried in from before the chart's start is never measured from, since its real time isn't known. Two readings at the same moment: the later one counts.
• transform_smoothing averages each rate with the ones before it (5 = the last five). transform_smoothing_time averages over a time window instead, weighted by time: on a meter, 15min is "how much it rose in the last 15 minutes, per hour". When both are set, the time window is used.
• On a column or combined chart the rate is averaged per group (not treated as a meter), so group_by: hour gives the mean kW of each hour.

Where transforms apply

The line, column, area, combined, range area, sparkline, trend, streamgraph, histogram, violin, beeswarm, heatmap, slope, dumbbell, waterfall, scatter, bubble, box plot, candlestick and 24-hour clock charts. On the 24-hour clock only number rings are transformed, and a transformed entity is averaged in each slot unless you set aggregate. With source: statistics, the box plot and candlestick transform the statistics' averages, which is coarse; history is the better source for a rate.

The climate chart and the wind rose don't apply transforms and the editor doesn't offer them; a transform left in the YAML after switching style is ignored.

When an entity also converts its unit, the conversion comes first and the transform works on the converted readings. A when condition is applied before the transform too.

In the editor: each entity's options have Transform (None (readings as they are), Running total or Rate of change). While any entity uses one, its keys appear: Running total starts again and the billing day, or Rate per, Smooth over readings and Smooth over time.

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; an entity's state is converted from its own unit from v2.2.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.