Repository navigation
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.
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: noneOnly type and entities are needed. Everything else has a default.
| 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+) |
An optional header for the card.
title: BatteriesWhich 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: ringA 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 doorIn 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.
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: truenone 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: descendingHow 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: 2Draws 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: falseFill 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."
Leaves out every entity that is unavailable or unknown, listed or matched.
hide_unavailable: trueShows 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: 5Colours 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: trueShows 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: 18withbelow: 22is "between 18 and 22". Awhenwith only anentityis 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
whenthat is half filled in (no entity yet) doesn't hide the card's. Entities matched by anincluderule take the card'swhen.
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.
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
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.
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_flowsthey 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: falsestacks 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 refusesgasandwater. -
devicesdraws each individual device from the Energy dashboard as a series of its own. - Other styles refuse
source: energywith a message listing the ones that take it.energy_flowsandenergy_splitneedsource: 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
entitiesyou 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.

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_increasingortotal, 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
currencywhen 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) unlessdecimalsis set. -
Tariff periods run from
fromtotoevery day in Home Assistant's time zone, past midnight whentois earlier ("23:00"to"07:00"), and follow clock changes. Where two overlap, the first one listed wins. Times no period covers takeprice; with noprice, they have none.nameandcolorare for the split columns' key; a period without a name is named by its price, and the time outside every period is "Standard". -
split: truestacks 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: trueprices each flow at the price set for it in the Energy dashboard's settings. -
Per entity,
cost: falseleaves a series out of the cost (it draws as usual), andcost: { 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
costand atransform, and the other styles refusecost. 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.

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)-
autowrites the summary from the readings;offleaves 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: truealso 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.

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

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)-
windowis a number ands,min,hord(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: historyon 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.

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: falseIn the editor: Read values with the keyboard, in the Chart section's Axes and gridlines.
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.
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: °CThe 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".

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/offon 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 %.

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, andmin(…),max(…),abs(…)andround(x)orround(x, places).^is worked out first, so-a^2is −(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;onandoffread as 1 and 0, sopower * switchworks. - A gap when any name has no number (unavailable, unknown), on a division by zero, or when the result isn't a number.
-
entityis 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 aname. With it, that entity is used. -
Unit:
unitwhen 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_increasingortotal), the formula is one too, soimport - exporton 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
transformapplies 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.
entities:
- entity: sensor.front_door_battery
name: Front door
icon: mdi:lockEach 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: 50In the editor, each of the three has a drop-down with Default, Number and Entity.
- Values outside
mintomaxare clamped for drawing, but the number shown is the real value. -
maxmust be greater thanmin. - When
minis below zero andmaxabove 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 formax, no marker fortarget) 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
unitset: a °C sensor withmaxfrom a °Finput_numbernow 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 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: 2unit 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,targetand bandfromvalues 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.
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.

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. Atotalmeter 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
unitset to an energy unit, the result is scaled to it: a W sensor withunit: kWhreads 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_dayof each month forbilling. Resets follow the calendar in Home Assistant's time zone.billingwith day 1 is the same asmonth; 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.

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_smoothingaverages each rate with the ones before it (5 = the last five).transform_smoothing_timeaverages over a time window instead, weighted by time: on a meter,15minis "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: hourgives the mean kW of each hour.

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
2hcovers 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: truedraws 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.
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.
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+) |
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: noneAn 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+)
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.
Start
Using it
-
Styles
- Bar
- Thin
- Segmented
- Tank
- Ring
- Needle
- Arc
- Line
- Area
- Column
- Combined
- Pie and donut
- Rings
- Pictograph
- Waffle
- Histogram
- Scatter
- Bubble
- Heatmap
- Box plot
- 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
- Marimekko
- Chord
- Battery grid
- Spiral
- Strip plot
- Cycle plot
- Duration curve
- Time in each state
- Badge
- Tile feature
- Options
- Visual editor
- Colour bands
Help