Skip to content

Options

tempus2016 edited this page Nov 21, 2026 · 19 revisions

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+), duration_curve, state_duration (v2.4.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 → Only show the series while… (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+)
cost price, tariff, currency, split none Chart → Cost → Show the cost (v2.4.0+)
summary auto, off or your own text auto Chart → Layout and sharing → Summary for screen readers (v2.4.0+)
show_summary true / false false Chart → Layout and sharing → Show the summary under the chart (v2.4.0+)
table_toggle true / false false Chart → Layout and sharing → Chart | Table switch (v2.4.0+)
table_change true / false true Chart → Layout and sharing → Table: change from average (v2.4.0+)
point_action action and window action: none Chart → Axes and gridlines → Tapping a point (v2.4.0+)
keyboard_nav true / false true Chart → Axes and gridlines → Read values with the keyboard (v2.4.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+). The v2.4.0 charts have theirs on Duration curve and Time in each state. Also from v2.4.0: a goal, the usual range and calendar events on the line chart, a fit line on the scatter chart, and for a tile card a Chartdeck tile feature.

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 the heading Only show this series while… with Entity, is in state, is above and is below (since v2.3.0; before that the labels were 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: Only show the series while… and the same four 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+)

A line chart with its export menu open at the top right: Save as PNG, Save as SVG, Copy CSV and Copy YAML

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.

cost (v2.4.0+)

Three cost charts: daily import cost stacked by tariff band (standard, off-peak and peak) with a key under the names; today's running cost from a half-hourly price; and daily cost read from long-term statistics with each column's value printed above it

Draws what the energy cost instead of how much was used, on the line, area and column charts.

type: custom:chartdeck-card
style: column
group_by: day
entities:
  - sensor.grid_import_energy
cost:
  price: sensor.electricity_rate   # an entity, or a fixed price per kWh such as 0.24
  tariff:                          # optional: prices by time of day
    - { from: "00:30", to: "05:30", price: 0.09, name: Off-peak }
    - { from: "16:00", to: "19:00", price: 0.32, name: Peak, color: red }
  currency: GBP                    # optional: Home Assistant's currency when left out
  split: true                      # column chart: stack each column by tariff band
Key Type Default Editor
price number or entity none Price entity or Price per unit
tariff list of periods, each with from, to, price and optionally name and color none Tariff periods → Add a tariff period
currency three-letter code, such as GBP or EUR Home Assistant's currency Currency
split true / false false Stack each column by tariff band (column chart, once there is a tariff period)
  • What is drawn. The line and area charts draw the running total over the span; the column chart draws each group's cost. The names row shows the total over the span, and the hover readout reads in money ("£4.82", "4,82 €"). The numbers on the value axis stay plain.
  • How a reading is priced. A meter (state class total_increasing or total, or any energy unit) is priced by how much it rose between readings, at the average price between them. A power sensor in W, kW or MW is added up over time, each stretch at the price then. The price is per kWh for energy (a Wh or MWh meter is converted) and per the meter's own unit for anything else, such as m³ of gas.
  • A price entity is read from its history, so each reading is priced at what the entity said at the time. Before its first known price the first one is used; while it is unavailable the last known price holds. History only reaches back as far as the recorder keeps it (10 days by default); before that the first known price is used. Negative prices lower the cost.
  • Pence and cents. A price entity's unit sets its scale. Prices in pence or cents (p/kWh, GBp/kWh, ct/kWh, c/kWh, ¢/kWh, öre/kWh) are read as hundredths of the currency, so a 30 p/kWh rate costs £0.30 a kWh. A price per MWh is read as a thousandth per kWh. Prices you type are in the currency per kWh.
  • Currency. The cost is shown in currency when you set it, otherwise in Home Assistant's own currency (from its general settings). Only when Home Assistant has no currency set does it fall back to the code in the price entity's unit (EUR/kWh), then euros. Money uses the currency's own decimals (2, or 0 for yen) unless decimals is set.
  • Tariff periods run from from to to every day in Home Assistant's time zone, past midnight when to is earlier ("23:00" to "07:00"), and follow clock changes. Where two overlap, the first one listed wins. Times no period covers take price; with no price, they have none. name and color are for the split columns' key; a period without a name is named by its price, and the time outside every period is "Standard".
  • split: true stacks each column by tariff band, with a key under the names row and a row per band in the hover readout. It is for the column chart, and draws on a chart that isn't stacked (stack: none).
  • Long-term statistics. A card reading statistics prices each hour's rise at that hour's average price (a price that changes on the half hour is averaged across the hour). A power sensor's hourly average is taken times the hour. Other series on a costed card that reads statistics also read each hour's rise.
  • The Energy dashboard. With source: energy, cost: true prices each flow at the price set for it in the Energy dashboard's settings.
  • Per entity, cost: false leaves a series out of the cost (it draws as usual), and cost: { price: sensor.export_rate } gives one entity its own keys, each winning over the card's.
  • With no price and no tariff period, the chart says "Set a price or a tariff to show the cost".
  • An entity can't have both cost and a transform, and the other styles refuse cost. The usual range can't be drawn on a costed series.

In the editor: under the Chart section's folds, Cost: Show the cost, Price entity, Price per unit, Currency and, on a column chart with tariff periods, Stack each column by tariff band. Then Tariff periods, each with From, To, Price, Name, Colour and Remove period, and Add a tariff period. While a cost is set, each entity's options have Count its cost and Its own price entity.

summary and show_summary (v2.4.0+)

Charts with their summary printed under them: a line that fell from 18.9 to 17.8 °C over 24 hours with its peak and "Now falling"; a two-series area chart with a sentence per series; a compact column chart named by day; and a chart with its own text

A history chart describes itself in a sentence or two for screen readers: "Rose from 18.1 °C to 22.0 °C over 6 h. Peak 23.1 °C at 14:10. Now falling."

summary: auto        # auto (default), off, or your own text
show_summary: true   # also print it under the chart (default false)
  • auto writes the summary from the readings; off leaves it out; any other text is read out as written.
  • A change of less than a tenth of the series' spread reads "Ended about where it started". A peak or a low is named only when it reads differently from the start and the end.
  • "Now rising", "Now falling" or "Now steady" is added while the span runs to now, from the latest value against the value a tenth of the span before it.
  • Times are clock times on a span of a day or less, and dates with times beyond. On a grouped column chart the peak is named by its group ("Wed, 18 Nov"), and there is no "Now …".
  • With several series each one gets its own sentence, after its name. Gaps are skipped, and a series with nothing recorded is left out.
  • Screen readers hear it either way; show_summary: true also shows it in small text under the chart.
  • It is on the line, area and column charts. The line chart describes the whole period, also when zoomed in, and small multiples have none.

In the editor: Summary for screen readers and Show the summary under the chart, in the Chart section's Layout and sharing.

table_toggle (v2.4.0+)

Charts switched to tables: a line chart of two rooms as hourly rows with each value and its change from the average; daily import as rows by day; and a minute-by-minute table, with a line and a column chart below left on Chart

Adds a Chart | Table switch at the end of the names row, to show the readings as a table instead of the chart.

style: column
group_by: day
table_toggle: true
table_change: true   # default: a "vs avg" column for each series
  • The table has a row per group (or per reading when ungrouped): the time, each series' value and, with table_change, how far each value is from that series' average over the span ("+9 %", "−4 %").
  • The average counts each group once; ungrouped, each reading counts for as long as it held. A total for a group still running (today so far) isn't compared and reads "so far".
  • An ungrouped history shows its latest 250 rows, and the caption says so ("Last 24 hours, latest 250 of 812 rows").
  • The table is as tall as the chart and scrolls, with the header row and the time column kept in view. Numbers and times follow your Home Assistant language and number format.
  • Series hidden with legend_toggle stay out of the table. Zoom, forecasts and earlier spans are not in it.
  • The choice of chart or table is remembered per card in the browser.
  • With header: hidden, a row with only the switch stays, so the chart can always come back.
  • It works on the line, area and column charts.

In the editor: Chart | Table switch in the Chart section's Layout and sharing, then Table: change from average once it is on.

point_action (v2.4.0+)

Hover readouts on a line, a column and an area chart, each ending in an Open in History link under the readings

Opens Home Assistant's History panel at the reading you tap, with every series of the chart.

point_action:
  action: history   # none (default) or history
  window: 2h        # how long a stretch to open, centred on the point (default 2h)
  • window is a number and s, min, h or d (30min, 2h, 1d), at most 31 days. The stretch never runs past now. A grouped reading opens its whole group: a day's column opens that day.
  • With a mouse, a click on the chart opens History at the reading nearest the pointer. A drag (to zoom or pan) is not a click, and with zoom on a double-click still resets the zoom.
  • On a touch screen, a tap shows the hover readout as before, now with an Open in History link. With tooltip: false, a tap opens History straight away.
  • Long-term statistics with no entity (from source: energy, say) are left out of the link. In small multiples each panel opens its own entity.
  • It is written as an object, like Home Assistant's own actions: point_action: history on its own is refused.
  • It works on the line, area and column charts.

In the editor: Tapping a point (Does nothing or Opens History there) and History window, in the Chart section's Axes and gridlines.

keyboard_nav (v2.4.0+)

A line chart of two rooms reached by the keyboard: a focus outline round the plot, a ring on the hall's latest reading and the hover readout showing both values; a column and a stacked area chart below

The line, area and column charts can be read from the keyboard. Each chart is one Tab stop; this is on unless you set keyboard_nav: false.

Key What it does
← and → The reading before or after, in the series in focus (the first press lands on the first series' latest reading)
↑ and ↓ The series before or after, at its reading nearest in time
Page Up and Page Down A tenth of the readings back or on
Home and End The first or last reading on show
Enter Opens the series' more-info dialog
Esc Lets go of the chart
  • The reading in focus gets a ring and the hover readout, and screen readers hear it ("Inside, Fri 20 Nov 14:05: 21.0 °C"). Synced charts follow it, as they follow the pointer.
  • The chart has a focus outline when reached by the keyboard, not when clicked.
  • With zoom on, the keys move only between the readings on show. The overview strip and the reset button keep their own keys.
  • Moving the mouse hides the ring; the next arrow carries on from where the pointer was.
  • Gaps and hidden series are skipped. Keys with Ctrl, Alt or Cmd are left to the browser.
  • The arrows follow the time axis as drawn, so → is later in every language.
  • Small multiples aren't read from the keyboard yet.
keyboard_nav: false

In the editor: Read values with the keyboard, in the Chart section's Axes and gridlines.

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)
state_map state: number pairs none Entities → row options → States as numbers (per entity only, v2.4.0+)
formula and vars text, and names with an entity each none Entities → row options → Calculate from other entities (per entity only, v2.4.0+)
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 (v2.2.0+), rolling (v2.4.0+), with its own keys none Entities → row options → Transform (per entity only, v2.2.0+)
cost false, or its own cost keys the card's cost Entities → row options → Count its cost, Its own price entity (per entity only, v2.4.0+)
when condition the card's when Entities → row options → Only show this series while… (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 Attribute, States as numbers, Name, Unit, Decimals, Icon, Minimum, Maximum, Target, its own Colours and its own three actions. Since v2.4.0 it also has Calculate from other entities, for a formula.

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".

state_map (v2.4.0+)

A step line of a hall thermostat's heating over the last 24 hours, at 100 while heating, 20 while idle and 0 while off, and a bar of the same entity reading "Idle"

Draws states that are words as numbers, so a heating action, a mode or an enum sensor can be charted. Set it per entity. It works on the state, or on the attribute when one is set.

entities:
  - entity: climate.lounge
    attribute: hvac_action
    state_map:
      heating: 100
      idle: 0
  • The bar, gauge or line is drawn at the mapped number; the value text still shows the word ("Heating"), as Home Assistant formats it.
  • States match exactly first, then ignoring case and spaces at the ends.
  • A state that isn't in the map is read as before: numbers stay numbers, on/off on a chart stay 1 and 0, and any other word is a gap.
  • In the editor, Add state fills in the entity's current state first, then the other states it is known to take (an enum sensor's options, a thermostat's modes or HVAC actions). The first state gets 0 and each one after it 100 more, so a two-state pair reads as 0–100 %.

formula and vars (v2.4.0+)

Three formula charts: lounge and outdoor temperature with their difference as a dashed third line; the hourly cost of power times price; and the hourly mean difference between two rooms as columns, followed by bars from a formula's current value, one of them unavailable

Works a series out from other entities: the difference between inside and outside, the power of two circuits added up, a power times a price. Set it per entity.

entities:
  - formula: "a - b"
    vars:
      a: sensor.lounge_temperature
      b: sensor.outside_temperature
    name: Inside less outside
  - entity: sensor.house_power        # optional: the entity the row opens and takes its icon from
    formula: "abs(p) / 1000 * c"
    vars:
      p: sensor.house_power
      c: sensor.electricity_price
    unit: £/h
  • What a formula can use: numbers, the names in vars, + - * / ^, brackets, a minus in front, and min(…), max(…), abs(…) and round(x) or round(x, places). ^ is worked out first, so -a^2 is −(a²). Nothing else runs: no templates, no code. A formula is at most 500 characters, with at most 10 names.
  • Every name needs an entity in vars. Names read the entity's state, not an attribute; on and off read as 1 and 0, so power * switch works.
  • A gap when any name has no number (unavailable, unknown), on a division by zero, or when the result isn't a number.
  • entity is optional. Without it the row opens the first name's entity, takes its icon, and is named by the formula text until you give it a name. With it, that entity is used.
  • Unit: unit when set; otherwise the unit every name shares (two temperatures in °C give °C); otherwise none, as for a power times a price. A unit that converts converts as usual. Decimals: decimals, else the entity's when every name shares the unit, else 2.
  • History joins each name's history in time, each holding its last value until it changes, so the chart has a point whenever any of them changed. It starts once every name has a reading.
  • Meters: when every name is a meter (state class total_increasing or total), the formula is one too, so import - export on a column chart shows the net change per day.
  • Long-term statistics are joined hour by hour. That is exact for adding and taking away; for a product it multiplies the hourly averages, which is close but not exact.
  • It works on every style that reads a value (bars, gauges and the rest) and on the history charts, including the badge's sparkline, and a transform applies on top. The state timeline, the 24-hour clock's state rings, the climate chart and the wind rose read words or their own attributes, so they ignore it, as does the recent range behind the gauges.

In the editor: each entity's options have Calculate from other entities, with a Formula field and an entity picker for each name the formula uses (Entity for a). A name you take out of the formula drops its entity. While the formula can't be read, a warning under it says why.

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, its rate of change or (v2.4.0+) a rolling statistic before it is drawn. Set it per entity, in its options; a card-wide transform does nothing.

Running total: transform: cumulative

A line chart of a grid import meter over 30 days as a running total that climbs steadily, drops to zero on the 15th and climbs again

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

A line chart of a heat pump's power in kW, worked out from its kWh meter as the rate the meter rose, smoothed over an hour

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
  • 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.

Rolling window: transform: rolling (v2.4.0+)

Four rolling-window charts: an office CO2 sensor's two-hour rolling mean with the readings faint behind it; mean, median, lowest and highest over six hours as four lines; a rolling mean broken where the readings have a gap; and columns of a three-hour rolling highest

entities:
  - entity: sensor.office_co2
    transform: rolling
    transform_window: 2h     # needed: s, min, h or d, up to 7 days
    transform_stat: mean     # mean (default), median, min or max
    transform_raw: true      # line chart: the readings faint behind it (default false)
Key Values Default Editor
transform rolling none Transform → Rolling window
transform_window a time up to 7 days: a number then s, min, h or d (30min, 2h, 1d) none (needed) Window
transform_stat mean, median, min, max mean Show (Mean, Median, Lowest, Highest)
transform_raw true / false false Keep the readings faint behind it

Draws, at each moment, the mean, median, lowest or highest reading over the window before it, so a CO₂ sensor that jumps about reads as a calm trend, or a 24 h rolling highest carries the day's peak along.

  • The window trails: the value at 14:00 with 2h covers 12:00 to 14:00. The chart loads a window's worth of history before its start, so its left edge already has a full window behind it.
  • Weighted by time: a reading holds until the next one, so a value that held for an hour counts sixty times one that held for a minute. The median is the value the readings were below half of the time. Lowest and highest take every value that held at any moment of the window.
  • Gaps are left out of the window. The rolling series is a gap only where the whole window is.
  • transform_raw: true draws the readings themselves as a thin faint line behind the rolling one, on the line chart.
  • The names row and hover readout show the rolling value.
  • One transform per entity, so a rolling window can't sit on top of a rate of change (which has its own smoothing).
  • The box plot, candlestick and the 24-hour clock's number rings apply it too, without loading the window early, so their first window is shorter.

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, 24-hour clock, spiral, strip plot and cycle plot charts, and (v2.4.0+) the duration curve. 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, Rate of change or, since v2.4.0, Rolling window). 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, or Window, Show and Keep the readings faint behind it.

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.

Clone this wiki locally