A built-in date navigation panel that lets users browse historical data by Day, Week, Month, or Year — without leaving the dashboard.

Setup

type: custom:statistics-graph-chart-card
show_date_picker: true
date_picker_position: top
entities:
  - entity: sensor.temperature_living
    color: "#ff6b35"

Navigation

The date picker bar shows the current period label with arrow buttons to move forward/backward:

• D / W / M / Y — switch between Day, Week, Month, and Year views
• ◀ ▶ — navigate to the previous/next period
• 📅 — open the calendar popup for direct date selection

Layout: the ‹ period › navigator and the D/W/M/Y + 📅 shortcuts can each sit left / center / right:

date_picker_nav_position: center
date_picker_shortcuts_position: right

Calendar & Presets

Click the calendar icon to open a panel with:

• Calendar grid — click two dates to select a custom range
• Quick presets — Today, Yesterday, This/Last Week, This/Last Month, This/Last Year, Last 7 Days, Last 30 Days, Last 12 Months, Last 2 / 3 / 5 Years (v4.04)

The calendar stays open after selection so you can adjust the range. Click the 📅 icon again to close it.

Group Sync

Cards with the same date_picker_group share their date selection. You don't need a visible date picker on every card — only one card needs show_date_picker: true. Other cards in the same group will follow along automatically.

# Card 1: Has the visible date picker — this is the "controller"
show_date_picker: true
date_picker_group: bedroom

# Card 2: No visible picker — just follows Card 1
date_picker_group: bedroom

# Card 3: Also follows Card 1
date_picker_group: bedroom

Changing the date on Card 1 updates all three cards. Cards 2 and 3 show no picker UI but their data range follows the group selection.

This is ideal for dashboards where you want one date picker controlling multiple charts without repeating the picker bar on every card.

The same mechanism exists for the other on-card controls: interval_picker_group for the Interval Picker, and pph_picker_group / group_by_picker_group for the on-card Points/Hour and Group By pickers — each group is independent.

Customizing Modes

Control which period buttons appear with date_picker_modes:

# Show only Month and Year
date_picker_modes:
  - month
  - year

# Lock to Month — buttons hidden, navigation centered
date_picker_modes:
  - month

When only one mode is listed, the D/W/M/Y buttons are hidden entirely and the navigation (◀ label ▶) is centered for a minimal look. The 📅 calendar icon stays visible on the right.

Scrollback (Extended Window) (new in v3.29)

The arrows jump period by period — for a quick peek into the recent past without leaving the current view, add extended_window_multiplier:

show_date_picker: true
extended_window_multiplier: 2   # render 2× the period, scroll back through the extra half

The card renders N× the selected period but opens showing exactly the period you picked, at its own scale and bucket density — then you can scroll horizontally into the extra history (scrollbar or mouse wheel, per scroll_mode). It follows the picker: on a Week view one extra week sits behind the current one; switch to Day and it's one extra day. The picker's header and arrows stay on the selected period — scrolling is a peek, the arrows remain the navigation. Also works without the date picker (extends hours_to_show or graph_start periods the same way).

With forecast data (data_attribute entities or forecast_horizon data whose points reach into the future — weather, prices): the chart opens with the current period in view (right edge at "now"), with the forecast reachable by scrolling right and history by scrolling left. This also works together with graph_start: normally graph_start cuts the window at the period's end, but with the multiplier active the forecast tail is rendered and scrollable, and the viewport spans the full selected period (so the scale doesn't creep as the day progresses). show_full_period is the exception — it keeps its "whole period, cut at its end" contract.

Controller card — pickers without a chart (v4.03)

A Statistics Graph Chart Controller is a one-row card that contains only the date-picker bar and drives every chart card that shares its group. Add it from the card picker (Statistics Graph Chart Controller), or turn any card into one with chart_mode: controller. It fetches no data and needs no entities.

# the controller
type: custom:statistics-graph-chart-controller
sync_group: home
card_header: Period
date_picker_modes: [day, week, month, year, last_1h, last_6h, last_12h, last_24h, last_7d, last_30d]   # the default set
date_picker_default_mode: last_24h    # optional: open here on every load

# a chart it drives — no picker of its own, just the same group
type: custom:statistics-graph-chart-card
sync_group: home
entities:
  - entity: sensor.living_room_temperature

• One bar, one active state — calendar periods (D/W/M/Y with ◀ ▶, the calendar popup with presets and custom ranges) and rolling windows (1H, 6H, 12H, 24H, 7D, 30D …) share the bar. Choose the buttons with date_picker_modes; date_picker_nav_position / date_picker_shortcuts_position align them.
• Reset — the ↺ button returns to date_picker_default_mode (or the first visible mode) and clears a custom range. A controller shows it by default (date_picker_reset: false hides it); a normal chart card gets it with date_picker_reset: true.
• Rolling hours are exact — 1H, 6H and 12H count elapsed hours, so a window that crosses a daylight-saving change is still 1, 6 or 12 hours long.
• Late joiners — a chart card that loads after the controller asks for the current period when it connects, so it never starts out of step. The selection is remembered per group in the browser.
• sync_group fills the picker group keys that are left empty (date_picker_group, pph_picker_group, group_by_picker_group, and interval_picker_group on chart cards), so one name is enough on both sides. Chart cards in a controlled group should not show a date picker of their own — if one does, both are masters and the last click wins.
• The controller can also host the Resolution and Group By pickers (Overlay tab in the editor, or show_pph_picker: true / show_group_by_picker: true). Reset clears those overrides too.
• A controller that has no remembered selection yet (first use in a browser, or the editor preview) asks its group for the current period before it broadcasts anything, so opening the card picker never resets a live dashboard.
• Layout: the card reports one row (rows: auto, full width in Sections view by default); override with grid_options. Chart-only options are ignored.
• Cards still running an older card version ignore the 1H/6H/12H modes when a controller selects them (they keep their own mode and follow the offset only).

Editor — the controller's editor shows the Calendar tab (Sync Group, Reset Button, Visible Modes, Default Mode, Window Step, alignment), the Overlay tab reduced to the Resolution / Group By pickers, and the Card Settings panel. On a regular card, Chart Mode → Controller does the same.

Rolling windows (Last 1H … Last 5Y)

Alongside the calendar modes, the picker offers rolling windows that always end at now: last_1h, last_6h, last_12h, last_24h, last_3d, last_7d, last_15d, last_30d, last_90d, last_180d, last_12m, last_2y, last_3y, last_5y. Unlike Day / Week / Month / Year (which snap to calendar boundaries), these show the last N up to the current moment, and the ◀ ▶ arrows jump a full N back/forward (e.g. the previous 7 days).

Use them two ways:

# Always open on the last 7 days
show_date_picker: true
date_picker_default_mode: last_7d

# Offer rolling buttons in the picker bar (shown as 24H / 7D / 30D …)
show_date_picker: true
date_picker_modes:
  - day
  - last_7d
  - last_30d

• As Default Mode (date_picker_default_mode) a rolling window is forced as the starting view on every load.
• As Visible Modes (date_picker_modes) the rolling options appear as extra buttons — 1H, 6H, 12H, 24H, 3D, 7D, 15D, 30D, 90D, 180D, 12M, 2Y, 3Y, 5Y — next to D/W/M/Y. Calendar modes are on by default; rolling buttons are off until you add them. In the editor the two families are shown under separate Calendar periods / Rolling windows headings, and on the picker bar a thin divider separates the D/W/M/Y buttons from the rolling ones so the two aren't mistaken for each other. (v3.30)
• The label reads e.g. Last 7 days at the current window, switching to a date range (May 16 – May 23) once you navigate back.
• The multi-year windows last_2y, last_3y and last_5y are anchored to the same day and time two, three or five calendar years back, so the arrows step a full 2 / 3 / 5 years. Pair them with auto_scale_points: true so the card buckets by month instead of trying to draw every interval, and expect last/first/diff/max aggregates to read from daily rows past roughly a year (the card logs a one-off console note when that happens). (v4.04)

Window Step

date_picker_step controls how many units make up one "window". Default 1 = the legacy behavior (each click moves one day, one week, one month, etc.). When you set it higher, the picker becomes a rolling N-unit window and prev/next buttons jump a full N units at a time.

# Last 4 weeks, prev/next jumps 4 weeks
show_date_picker: true
date_picker_step: 4
date_picker_modes:
  - week

# Last 30 days, prev/next jumps 30 days
date_picker_step: 30
date_picker_modes:
  - day

The label adapts automatically: step > 1 shows the date range (Mar 11 – Apr 7), step = 1 keeps the existing single-period labels (April 2026, Apr 1 – Apr 7).

Editor: General Settings → Calendar tab → Date Navigation → Window Step (appears next to Visible Modes when the date picker is enabled)

Behavior

Editor

General Settings → Calendar tab → Date Navigation → Date Picker toggle. Position and Group options appear on the same row. The Group field is always editable — even when the Date Picker toggle is off — so you can assign a group to cards that don't show their own picker. When enabled, a Visible Modes section appears below with D/W/M/Y checkboxes plus the rolling options (24H / 3D / 7D … 12M / 2Y / 3Y / 5Y), and a Default Mode dropdown that also lists the rolling windows. The Date Nav and Shortcuts dropdowns control where the navigator and the mode buttons sit in the bar.

Notes

• Cannot be used together with energy_date_sync — enabling one disables the other
• Date picker state is persisted in localStorage and restored on page reload
• When viewing the current period, the X-axis extends to the end of the period with empty space after the current time
• Cards with only date_picker_group (no show_date_picker) use their normal hours_to_show until a sync event arrives from a card in the same group

Append each entity's Home Assistant area to its label. Handy when a card mixes rooms, and essential with integrations like Advanced History that hand several entities the same friendly name (three Heating Temperature sensors, one per room, otherwise indistinguishable):

type: custom:statistics-graph-chart-card
include_area_names: true   # default false
entities:
  - entity: sensor.lounge_heating    # friendly_name: "Heating Temperature"  (area: Lounge)
  - entity: sensor.office_heating    # friendly_name: "Heating Temperature"  (area: Office)
  - entity: sensor.fridge            # friendly_name: "Fridge Temp"          (area: Kitchen)
  - entity: sensor.lounge_lamp       # friendly_name: "Lounge Lamp Power"    (area: Lounge)

Legend result:

Heating Temperature · Lounge
Heating Temperature · Office
Fridge Temp · Kitchen
Lounge Lamp Power              ← already says "Lounge", not doubled up

Only the area name (v4.07)

When every sensor on the card stands for one room, the entity name is noise: what you want to read under each value is just the room. use_only_area_name: true replaces the label with the area alone — the value on top, Master Bedroom below it — in the state row, legend, tooltip, stats, exports and the pie, ranking and other summary charts:

type: custom:statistics-graph-chart-card
use_only_area_name: true   # default false
entities:
  - entity: sensor.bedroom_multisensor_temperature   # friendly_name: "Monitorbug-Morty Multisensor Temperature"  (area: Master Bedroom)
  - entity: sensor.theatre_rack_temperature          # no area of its own — its device is in Theatre Room
  - entity: sensor.garage_temperature                # no area

State row result:

21.4 °C            24.1 °C         14.2 °C
Master Bedroom     Theatre Room    Garage Temperature   ← no area, keeps its own name

The rules below apply unchanged: the area comes from the entity or, failing that, its device; an explicit name: is never touched; a comparison ghost reads Master Bedroom (previous period). The "name already contains its area" rule has nothing to do here — Master Bedroom Humidity simply becomes Master Bedroom, so two entities in the same room get the same label; give one of them a name: if you need to tell them apart. The area is the whole label, so the Attribute names options do not touch it (an entity without an area still follows them); for Current temperature · Lounge use use_only_attribute_name together with include_area_names. use_only_area_name and include_area_names are alternatives: the visual editor turns one off when you switch the other on, and in YAML use_only_area_name wins if you set both.

Rules

• Every entity that has an area gets it — there is no duplicate detection. A rule that only fired on collisions would make your legend change shape whenever an unrelated entity was added or removed; if you switch this on, you want the areas.
• The area is taken from the entity's own area registry entry; if it has none, the card falls back to the entity's device area. If neither resolves, the name is left unchanged.
• A friendly name that already contains its area (e.g. Lounge Heating Temperature in the Lounge) isn't doubled up.
• An explicit name: (including template names) is your own label and is never modified.
• Applies to the state row, legend, tooltip, stats, exports and the editor's entity list, so every surface agrees.
• Comparison ghosts inherit the parent's label — Heating Temperature · Lounge (previous period), or Lounge (previous period) with use_only_area_name.
• Off by default. Resolution is a couple of registry key-lookups per configured entity, so the cost is negligible.

Editor

General Settings → Chart tab → Visual Options → the Area names and Area names only (v4.07) toggles (next to the legend options). Switching one on turns the other off.

When a card plots two attributes of the same entity, both series carry that entity's friendly name — so the legend and the tooltip show the same label twice and there is no way to tell which line is which:

entities:
  - entity: climate.lounge_heating
    attribute: current_temperature     # legend: "Lounge Heating"
  - entity: climate.lounge_heating
    attribute: temperature             # legend: "Lounge Heating"   ← identical

Two card-level options qualify the label with the attribute, everywhere the name appears — state row, legend, tooltip, stats and exports:

include_attribute_name: true      # "Lounge Heating · Current temperature"
use_only_attribute_name: true     # "Current temperature"

Details:

• Only rows that actually plot an attribute change. An entity graphed on its own state has no attribute name, so it is left exactly as it was — which means you can turn these on for a whole card without touching its ordinary series.
• An explicit name: always wins, as everywhere else in the card.
• The attribute label comes from Home Assistant's own translated attribute name when your HA version provides one, so a German dashboard reads Zieltemperatur. Otherwise the attribute key is humanised: current_temperature → Current Temperature. The runtime attribute picker uses the same label, so the dropdown and the chart always name an attribute the same way (v3.32).
• With ref_entity, both halves of the combined name are qualified — Current Temperature - Target Temperature rather than one attribute minus a bare entity name.
• Rows using data_attribute (an attribute array such as a forecast) are never renamed after attribute:, since that is not what they plot.
• If you switch attributes with the runtime attribute picker, the label follows.
• The two options are alternatives, not a stack. In the visual editor, switching one on turns the other off; in YAML, use_only_attribute_name wins if you set both.
• It cooperates with include_area_names: the "name already contains its area" rule is evaluated against the label you will actually see, so Lounge Heating keeps its area suppressed while Current temperature correctly gains · Lounge.
• With use_only_area_name the area is the label: an entity whose area resolves reads Lounge whatever the attribute options say, while entities without an area still follow them. For the attribute and the room, combine use_only_attribute_name with include_area_names — Current temperature · Lounge (v4.07).

Editor

General Settings → Chart tab → Visual Options → the Attribute names and Attribute names only toggles, next to Area names and Area names only.

Syncs the card's time range with Home Assistant's Energy dashboard date picker or the energy-period-selector-plus custom card.

Setup

type: custom:statistics-graph-chart-card
energy_date_sync: true
entities:
  - entity: sensor.energy_consumption
    color: "#ff4757"
    aggregate_func: sum
  - entity: sensor.solar_production
    color: "#2ecc71"
    aggregate_func: sum

Place the card on the same dashboard as an Energy date picker. When the user selects a day, week, month, or custom range, this card automatically updates to show the same period.

Behavior

Compatible with

• HA's built-in Energy dashboard date picker (DAY / WEEK / MONTH / YEAR)
• energy-period-selector-plus custom card
• Any card that uses HA's energy data collection system

Editor

Chart Settings → Calendar tab → Date Navigation → Energy Date Sync toggle, with the Key input next to it for energy_collection_key (v4.02).

Notes

• When energy_date_sync is active, it overrides hours_to_show and the interval picker selection
• Running several dashboards with separate energy-date-selection cards? Bind each card to its own picker with energy_collection_key — same key as that dashboard's selection card (HA requires the key to start with energy_) (v4.02)
• Period changes made in the Energy dashboard are picked up instantly — no polling, no refresh delay
• If the Energy panel hasn't loaded yet, the card retries every 2 seconds for up to 60 seconds

Extends the X-axis to cover a complete calendar period, leaving empty space after the current time. A dashed vertical "now" line marks where live data ends.

graph_start_hour: 0
hours_to_show: 24
show_full_period: true    # X-axis: 00:00 → 23:59, empty after now

The end of the period is determined by graph_start:

With Energy Date Sync

show_full_period also works with energy_date_sync: true. When the energy date picker selects a current period (today, this week, this month), the X-axis extends to the full period end. Past periods display in full as before.

energy_date_sync: true
show_full_period: true    # energy picker "This Month" → X-axis: Apr 1 → May 1

This is especially useful for:

• Imported data (energy, gas) that arrives with a few days delay — the graph shows the gap instead of filling it with the last known value
• Day comparison with offset — today's card shows a partial day with empty space; yesterday's card (offset: 24) shows a complete day
• Weekly/monthly dashboards — see the full period at a glance with the "now" marker
• Energy dashboard — combine with energy_date_sync to see the full billing period
• Solar forecast rows (solar_forecast: true) — a synced or date-picker window without it ends at now and is then stretched to the last forecast hour; with it the card stays on the selected period and the forecast is clipped to it

Editor: General Settings → Calendar tab → Time Window → Show Full Period checkbox

Visualize data over weeks, months, and years with calendar-aware grouping and native HA statistics.

Weekly, Monthly, and Yearly Grouping

group_by: week
graph_start: month         # this month's weeks
aggregate_func: change     # consumption per week
graph_type: bar

group_by: month
graph_start: year          # start from Jan 1

group_by: year
hours_to_show: 87600       # ~10 years
aggregate_func: change     # annual consumption
graph_type: bar

When group_by is set to date, week, month, or year, the card fetches data using native HA statistics periods (period: 'day', 'week', 'month'). Year mode fetches monthly data and aggregates client-side. This enables Home Assistant's native change column for counters (a change series on a sensor without that column — state_class: measurement — reads hourly rows instead, like diff, max, first and last on such sensors (v4.06)) and bypasses the database retention limit — you can display a full year of data even if your recorder purge is set to 10 days.

Mixing groupings in one chart (v4.05)

A daily series and a monthly total of the same sensor — or a daily temperature line with monthly energy bars — can share one chart. Each entity may carry its own group_by; the chart's time grid is the finest grouping in use, and every series grouped coarser than that grid is drawn as calendar cells on it:

type: custom:statistics-graph-chart-card
graph_start: year
group_by: date
entities:
  - entity: sensor.heat_pump_energy
    name: Monthly
    graph_type: bar
    aggregate_func: change
    group_by: month            # monthly cells on the daily grid
    y_axis: secondary          # kWh on the right axis
  - entity: sensor.outside_temperature
    name: Temperature
    aggregate_func: avg        # daily mean, drawn on top

• The monthly bars span their whole calendar month (real spans on the daily axis, not equal-width slots); a window that starts mid-month gets a partial first cell. List the coarse entity first so it draws behind the finer ones.
• The tooltip shows the day's values and the containing month's total; stacking never mixes different grids.
• The grid follows the finest grouping: group_by: month on the card with group_by: date on one entity gives a daily grid where the other entities become monthly cells — the same chart as date on the card with month on them. Only raw/interval cannot be set per entity, and nothing changes while the card is grouped by raw.
• Y axis: a monthly total is ~30× a daily value in the same unit, so give it y_axis: secondary (its ticks sit at the same heights as the left axis, both zeros on the shared baseline) or independent (private hidden scale). Editor: Entities → entity → Data → Group By.

Auto-Routing to Long-Term Statistics

Even in interval mode with short ranges (hours_to_show ≤ 24), the card auto-routes to long-term statistics in three cases:

1. Any entity declares statistic_id explicitly — the user vouches that the entity has long-term statistics available. Useful for entities that exist only in the statistics database (Gazpar, Linky, etc.) or for forcing the route.
2. hours_to_show > 240 (≈ 10 days, the typical recorder retention) — statistics is the only source that can serve the range, so the card switches automatically.
3. Missing recorder coverage (v4.06) — when the raw history of a data_source: auto sensor does not reach the start of the window (no recorded state at or before the window start, or a recorded state followed by a gap of at least 2 hours / a quarter of the window during which the long-term statistics show the value moving), that sensor is read from 5-minute statistics for that refresh. A sensor that simply did not change stays on raw history; data_source: history opts out.

In both cases the route is conditional on every relevant entity having long-term statistics available — meaning a state_class of measurement, total, or total_increasing, or an explicit statistic_id. If any entity in the card lacks LTS, the route falls back to the regular history API to keep that entity working.

When the requested range exceeds 10 days but some entities lack LTS, a console warning is printed once listing the offending entities and explaining how to enable state_class in HA.

Date picker, synced picker groups and the Controller card (v4.04) — a picker view of a day or less (Day, 24H, 12H, 6H, 1H, today so far, or a short custom range) that reaches no further back than about 10 days is treated like a short hours_to_show card and reads raw recorder history, so short spikes keep their real height. Longer views (Week, Month, 7D, 30D …), older days, cards that contain an energy counter (total / total_increasing), a statistic_id, a ref_entity or a price_entity, and Energy-dashboard sync keep using long-term statistics. If the recorder no longer holds the start of the window (a purge_keep_days shorter than the window, a purged or re-created sensor, or statistics written for hours the recorder never recorded), the card switches that sensor to statistics by itself — on picker days and, since v4.06, on every short hours_to_show / interval-picker window. Set data_source: statistics to keep the smoother statistics view on picker days.

Statistics store 5-minute averages, which flatten bursts shorter than a few minutes. On long views, use aggregate_func: max when the peak matters more than the average. Statistics averages are also weighted by time: a 5-minute row holds the value averaged over the minutes it was valid, whereas a bucket built from raw history averages the readings recorded inside it, each counting once. A sensor that changes rarely (a setpoint held for 59 minutes, then changed once) shows the new reading as that hour's avg on raw history and the time-weighted value on statistics, so the same hour can read differently on a 24-hour and a 48-hour card. Sensors that report at a steady pace give the same number either way.

Graph Start Anchoring

When graph_start is set, hours_to_show is ignored — the calendar period directly determines the start:

Editor: General Settings → Calendar tab → Time Window → Graph Start

Year starting in another month (v4.05)

A heating season, a school year or a fiscal year does not start on 1 January. year_start_month moves the start of the Year period:

show_date_picker: true
date_picker_default_mode: year
year_start_month: 7              # 1 Jul → 30 Jun, header reads 2026/27
group_by: month
entities:
  - entity: sensor.gas_consumption
    aggregate_func: change
    graph_type: bar
    compare: last_year           # ghost = 1 Jul 2025 → 30 Jun 2026

The same key shifts graph_start: year (with show_full_period the axis then runs to 30 June). It only moves the window: the month buckets, the tick labels and the Month / Week periods stay on the calendar. Every card in a date_picker_group should carry the same value — the group shares mode and offset, each card computes its own window. Editor: Chart Settings → Calendar → Time Window → Year Starts In.

Graph Start: Tomorrow

graph_start: tomorrow sets the window to tomorrow 00:00 → end of day — ideal for next-day spot prices (Nord Pool, EPEX, Tibber) via data_attribute. The window extends into the future automatically without show_full_period.

type: custom:statistics-graph-chart-card
card_header: Tomorrow Spot Prices
graph_start: tomorrow
group_by: hour
entities:
  - entity: sensor.nord_pool_fi_contract_current_price
    data_attribute: tomorrow_hourly
    data_time_field: start
    data_value_field: value
    graph_type: bar
    decimals: 2
    unit: c/kWh

X-Axis Interval

Manual control over tick spacing:

x_axis_interval: 2h    # Every 2 hours (00:00, 02:00, 04:00…)
x_axis_interval: 1d    # Daily (midnight)
x_axis_interval: 1w    # Weekly (Mondays)
x_axis_interval: 1M    # Monthly (1st of month)

Available presets in the editor: Auto, 1H–12H, 1D, 2D, 7D, 1W, 2W, 1M, 3M.

Editor: General Settings → X-Axis → X Axis Interval

Axis Style: matching Home Assistant's own charts (v4.03, widened in v4.04)

By default the card draws its axes and grid deliberately subtler than Home Assistant's built-in charts: labels use the theme's secondary text colour with some transparency, and the grid is a faint neutral grey. If you would rather have the card look exactly like the core statistics-graph card next to it, switch the axis style:

axis_style: native

native takes the label colour, size and grid colour from the same theme variables Home Assistant's charts use (--primary-text-color at 12 px for the labels and date markers, --divider-color for the grid), so the card follows light, dark and custom themes without any fixed colours in your YAML. Options you set explicitly (x_axis_color, x_grid_opacity, …) still override the preset, and the editor placeholders show which value applies.

(v4.04) native also covers the per-entity legend — the one you get with show_in_legend on an entity. Its names and values switch to --primary-text-color at full strength, and the values grow to the same 12 px as the axis labels, instead of the card's dimmer, smaller look. The MIN / AVG / MAX labels stay small and dim so the value still reads first, and the compact legend (show_legend) is unchanged — it was already using the theme's main text colour at 12 px.

There is no legend-only switch. If you want the dimmer legend back you have to go back to axis_style: subtle, which also returns the axes and grid to the card's own look — write the individual axis options out explicitly if you want to keep the native axes.

Editor: Card Settings → Card Styling → Axis Style

Grid Customization

Control the appearance of horizontal (Y) and vertical (X) grid lines independently.

y_grid_style: solid      # dashed (default), solid, dotted, long-dash
y_grid_width: 0.5         # thickness in px (default: 1)
y_grid_color: "rgba(255,255,255,0.1)"  # any CSS color or {{ template }}
y_grid_opacity: 0.3       # 0–1 (default: 0.15)

x_grid_style: dotted
x_grid_width: 0.5
x_grid_color: "var(--divider-color)"
x_grid_opacity: 0.3

Editor: Y Axis tab → Grid section, X Axis tab → Grid section

Smart X-Axis Labels

The X-axis automatically adapts to the group_by setting:

• Week — Ticks on Mondays: "3 Mar", "10 Mar"
• Month — Ticks on the 1st: "Jan", "Feb" (with year when spanning multiple years)
• Date — Daily ticks: "3 Mar", "4 Mar"
• Hour — Hourly ticks; midnight shows date instead of "00:00"

In interval mode, midnight labels also show the date for any view longer than 12 hours.

Everything week-shaped on the card follows Home Assistant's "First day of the week" user setting (your profile page) — no YAML, no card option.

What follows the setting

• Weekly buckets — group_by: week buckets start on your configured weekday
• Date picker — the Week view's window and the calendar popup's day grid both start on that day
• X-axis ticks — weekly tick marks (automatic weekly labels and x_axis_interval: 1w) land on that weekday
• Box Plot — weekly box buckets align to the same boundary

Automatic (the setting's default) derives the first day from your language, exactly like the rest of HA — Monday for most European locales, Sunday for en-US.

Recorder note

Home Assistant's recorder computes weekly long-term statistics Monday-anchored on the server — there is no Sunday-based weekly row to fetch. When your week starts on any day other than Monday, the card transparently fetches daily statistics rows instead and builds the weekly buckets client-side, so totals and change aggregates stay correct. Nothing to configure. The same applies when the card's time zone differs from the Home Assistant server's: daily, weekly and monthly rows are stamped at the server's midnight, so the card then reads hourly statistics (for windows up to a year) and builds the day / week / month cells in the card's own zone.

Compare the same sensor across different time periods by adding multiple entity entries with different offset values. Each offset shifts that entity's data backward in time while keeping it aligned on the same graph.

hours_to_show: 168
entities:
  - entity: sensor.energy_consumption
    name: "This week"
    offset: 0
    color: "#ff4757"
  - entity: sensor.energy_consumption
    name: "Last week"
    offset: 168
    color: "#378ADD"
  - entity: sensor.energy_consumption
    name: "2 weeks ago"
    offset: 336
    color: "#2ecc71"

How It Works

• offset: 168 means "fetch data from 168 hours (7 days) before the current display window"
• The fetched data is time-shifted forward to align with the current window on the X axis
• All rendering features work at full quality — line, bar, step, fill, gradient, points, tooltips, stacking, zoom
• Each entity with an offset gets its own API call with the correct time range

Common offset values

Dynamic Offset via Helper Entity

Instead of a fixed number, you can point offset to any HA entity whose state is a number (in hours). The card reads the entity's current state and re-fetches history automatically when it changes.

entities:
  - entity: sensor.energy_consumption
    name: "Current"
  - entity: sensor.energy_consumption
    name: "Comparison"
    offset: input_number.comparison_offset
    color: "#378ADD"

This works with any entity type — input_number, template sensors, or any sensor that outputs a numeric state. Combine with HA template sensors for fully dynamic comparisons:

# In HA configuration.yaml
template:
  - sensor:
      - name: "Dynamic Offset"
        state: "{{ 24 if now().weekday() < 5 else 168 }}"
        unit_of_measurement: "h"

Editor

Entity → Advanced tab → Advanced Calculations → Offset (in hours).

Notes

• Offset entities do not receive live WebSocket updates (they show historical data)
• The state row, sparkline, and gauge correctly display the last value from the offset time window — not the live entity state
• Works with all chart modes that support multiple entities
• Can be combined with value_transform, value_factor, and all other entity options
• Each offset generates a separate cache entry, so switching between views is fast

Overlay a faded "ghost" of the same entity from a previous period underneath the main series — today vs yesterday, this week vs last week, this month vs last month — with a single per-entity compare option. Unlike a manual Time Offset entry, compare needs no duplicate entity: the ghost inherits the main entity's whole configuration and stays in lock-step with it. Since v3.26, compare also accepts a list of comparisons — one ghost per entry, each reaching further back via periods_back — see Multiple comparisons below.

Minimal setup

type: custom:statistics-graph-chart-card
card_header: Power — Today vs Yesterday
hours_to_show: 24
entities:
  - entity: sensor.power_consumption
    compare: yesterday

Short forms

Styled example (object form)

For full styling control, use the object form — every sub-option is optional:

type: custom:statistics-graph-chart-card
card_header: Energy — This Week vs Last Week
hours_to_show: 168
group_by: date
entities:
  - entity: sensor.energy_daily
    name: Energy
    graph_type: bar
    aggregate_func: change
    color: "#2ecc71"
    compare:
      period: last_week      # which period the ghost shows
      color: "#9b59b6"       # empty = faded main color
      opacity: 0.6           # 0.05–1
      line_style: solid      # dashed (default) | solid | dotted
      line_width: 1.5        # empty = same as main
      show_fill: true
      show_points: false
      show_in_legend: true   # empty = inherit the main entity's setting
      show_in_compact_legend: false   # empty = inherit; false leaves only the ghost out of the compact legend
      show_delta: true       # Δ% next to the main value in the tooltip

In the tooltip, each comparison row is preceded by a small line showing that ghost value's actual date and time (hover 15 Jul, 14:00 and the previous-period row is headed by 14 Jul, 14:00 for yesterday), so it is always clear which moment is being compared.

Sequential layout (new in v4.02)

layout: sequential turns the overlay into a timeline: the X axis doubles backward and the previous period is drawn where it actually happened, directly before the live window — past on the left (dashed), present on the right (solid), meeting in the middle.

entities:
  - entity: sensor.temperature
    compare:
      period: previous_period
      layout: sequential

Notes:

• Works with period: previous_period on line/bar (timeline) charts; other periods and chart modes keep the overlay drawing.
• The tooltip shows each half's real date and time, and show_delta does not apply (the two halves never share an X position).
• Brush zoom works across the whole extended axis — you can zoom into the past half, the seam, or the live half, and the Y axis follows the visible data as usual.

Multiple comparisons (list form) (new in v3.26)

compare also accepts a list of comparison objects — one ghost series per entry. Each entry takes the full sub-option set above plus periods_back, which sets how many periods back that ghost reaches:

type: custom:statistics-graph-chart-card
card_header: Power — vs the last two periods
hours_to_show: 24
entities:
  - entity: sensor.power_consumption
    compare:
      - periods_back: 1        # previous period
      - periods_back: 2        # two periods ago
      - periods_back: 3
        line_style: dotted
        color: "#9b59b6"

• Follows the date picker. With the picker on Week, the entries above show the last three weeks; switch to Year and the same config shows the last three years — calendar-aligned in Month/Year modes, leap years handled.
• Each ghost is distinct. Later entries fade progressively by default (opacity 0.45 → 0.30 → 0.20 …), and legend entries beyond the first read "Name (previous period ×2)", "… ×3", and so on.
• Per-ghost tooltip. Every ghost row is headed by its own date sub-header, and with multiple comparisons each ghost row carries its own Δ% against the current value. With a single comparison the tooltip looks exactly as in v3.25 — one date sub-header and the Δ% next to the main value.
• Every entry still takes the full style set (period, color, opacity, line_style, line_width, show_fill, show_average, show_points, show_in_legend, show_in_compact_legend, show_delta, hide_on_load), and hiding the main series from the legend hides all of its ghosts.
• Existing single string/object compare configs are untouched — the list form is purely additive.

Behavior

• The ghost is drawn faded and dashed under the main series and is named "<main name> (previous period)" — the suffix follows the dashboard language.
• previous_period shifts by the current window length. In the date picker's Month / Year modes the shift is calendar-aware: July compares against June, wall-clock aligned, and month-end dates are clamped (Mar 31 → Feb 28/29). yesterday, last_week and the picker's Day / Week modes shift by whole days, wall-clock anchored at the window start (23 or 25 hours across a daylight-saving change); a number of hours stays exact.
• A main entity with its own offset compares against the previous period of its shifted window.
• Clicking the entity in the legend or its state row toggles the main series and its ghosts together.
• (improved in v3.28) Under stacked: true, ghosts stack with each other — the previous period appears as its own faded stacked column next to the current one (one ghost stack per comparison entry, honoring stack_group and the main entity's own stacked override (v4.07)). Ghosts never stack onto the current period and stay excluded from the tooltip's grand Total.
• (new in v3.28) With stacked comparisons the tooltip also shows the previous period's stack total — e.g. "Aktuell Total (previous period)", fully translated — and the current stack's Total row carries a Δ% against it.
• Ghost values go through exactly the same aggregation pipeline as the main entity (aggregate_func, points_per_hour, group_by, transforms) — the comparison is truly like-for-like.
• Timeline and State Timeline charts (State Timeline since v4.02). Ignored for candlestick, fixed_value, and data_attribute entities, and in sparkline mode.

Editor

Per-entity → Graph tab → Period Comparison section (shown in Timeline and State Timeline modes). Redesigned as a list in v3.26:

• The section starts empty with an Add Comparison button; each click adds one comparison row and steps the default Periods Back automatically (1, 2, 3 …).
• Each row holds a period select (labels now read Previous Period / Day Before / Week Before / Month Before / Year Before — only the labels changed, the YAML values are still previous_period, yesterday, last_week, last_month, last_year), a Periods Back input, line style, color, opacity, a Layout dropdown (Overlay | Sequential — enabled while the period is Previous Period, v4.02), a Show Δ% in tooltip toggle, and a delete button.
• Legacy string/object compare configs load into the list unchanged, and a one-row list commits back to the legacy short form — your YAML stays as compact as before.

Some sensors expose a forecast value — their current state represents what is predicted for N hours in the future, not what is happening right now. Typical examples:

• sensor.solcast_pv_forecast_leistung_in_1_stunde — PV power expected in 1 hour
• A template sensor whose state is "temperature in 3 hours"
• A weather forecast exposed as a numeric future-hour prediction

Plotting these directly is misleading: the line shows each prediction at the time it was recorded, not at the time it is predicting. forecast_horizon: N fixes this by shifting each recorded data point forward by N hours on the X-axis so every point lands at the moment it is forecasting.

type: custom:statistics-graph-chart-card
graph_start_hour: now
show_full_period: true
entities:
  - entity: sensor.solcast_pv_forecast_leistung_in_1_stunde
    name: "Forecast +1h"
    forecast_horizon: 1

The result: a line that extends 1 hour into the future past the "now" marker, representing the forecast for each upcoming moment. The X-axis end is automatically extended by the largest forecast_horizon across all entities so shifted points stay visible.

Matching the horizon to the sensor

The forecast_horizon value should match the actual prediction horizon the sensor represents:

Setting a value that doesn't match the sensor's real horizon will still shift the line — but the displayed time no longer corresponds to what the sensor is actually predicting.

Negative horizon — overlay tomorrow's forecast onto today

Some forecast integrations (Solcast PV, EPEX spot prices, weather APIs) expose future data through entity attributes — a single sensor whose attributes contain an array of timestamped points covering the next 24–48 hours. Combined with data_attribute, you can plot this future data directly. But what if you want to see tomorrow's forecast on today's chart timeline for an at-a-glance comparison?

A negative forecast_horizon shifts each point backward in time. Setting -24 moves tomorrow's points 24 hours earlier so they appear at today's clock positions:

type: custom:statistics-graph-chart-card
show_legend: true
entities:
  - entity: sensor.solcast_pv_forecast_tomorrow
    data_attribute: detailedHourly
    data_time_field: period_start
    data_value_field: pv_estimate
    name: "Tomorrow's forecast (shown today)"
    forecast_horizon: -24

The X-axis stays anchored to today — only the data slides into view. Combine with the live PV sensor (no horizon) on the same chart to see today's reality next to tomorrow's prediction, both aligned to the same hours.

Combining with offset

forecast_horizon and offset are orthogonal:

• offset shifts the fetch window backward (for past-period overlay comparison)
• forecast_horizon shifts the display forward (positive) or backward (negative)

Both can be used on the same entity. Example: overlay yesterday's 1-hour forecast sensor onto today's timeline, shifted 1h forward:

entities:
  - entity: sensor.solcast_pv_forecast_leistung_in_1_stunde
    offset: 24            # fetch yesterday's recordings
    forecast_horizon: 1   # show them shifted 1h forward
    name: "Yesterday's +1h forecast"

Editor

Entity → Advanced tab → Forecast Horizon (in hours, supports decimals — including negative values).

Notes

• Leave empty (or 0) to disable — the sensor plots at its recording time as before
• The fetch window is extended backward by the largest horizon so past recordings can be retrieved and shifted forward into the visible future range
• Works with live state updates — new recordings appear on the chart at recording time + horizon
• Multiple entities can use different horizons — the X-axis is extended to cover the largest one

Change the data resolution and the bucketing strategy directly on the card — no editor round-trip.

Setup

type: custom:statistics-graph-chart-card
show_pph_picker: true
show_group_by_picker: true
group_by_picker_position: right
entities:
  - entity: sensor.power

Behavior

• Each dropdown starts on Auto (…), showing your configured value; picking anything else overrides it for this card only.
• Selections persist across reloads and take priority over Auto Scale while active.
• The Group By picker offers Interval, Hour, 2H / 3H / 4H / 6H / 12H, Date, Week, Month and Year.

Group Sync

Each picker has its own, fully independent sync group — same mechanism as date_picker_group:

# Controller card
show_pph_picker: true
pph_picker_group: page

# Receiver cards — no picker shown, still follow
pph_picker_group: page

pph_picker_group and group_by_picker_group don't interact: a card can follow one page-wide resolution group and a different bucketing group (or none).

Editor

General Settings → Overlay tab → Card Overlays → Points/Hour Picker and Group By Picker rows. The Group fields are always editable, even while the toggles are off.

group_by: raw turns bucketing off entirely: every recorded sample is drawn at its exact timestamp, with no averaging and no resampling — points_per_hour is ignored.

type: custom:statistics-graph-chart-card
group_by: raw
hours_to_show: 24
entities:
  - entity: binary_sensor.front_door
    name: Front Door
    graph_type: step
    state_map:
      - value: "off"
      - value: "on"

When to use it

• Step charts of binary / state sensors — a door, pump, or heating-demand signal changes state at precise moments; bucketing smears those edges. Raw mode preserves every transition exactly where it happened.
• Sensors that record few, meaningful samples where a value interpolated into buckets would be misleading.

Editor

The Group By dropdown offers "Raw (no grouping)" whenever at least one entity uses graph_type: step — and always when the config already contains group_by: raw.

Apply a JavaScript expression to every data point before graphing. The transform has access to the current value and series-level statistics, making it possible to normalize, compare, and reshape data in ways that weren't possible before.

Available variables

All variables are computed after value_factor is applied, before the transform runs.

Normalize to zero

Display cumulative meter readings as relative consumption starting from zero:

entities:
  - entity: sensor.gas_meter
    value_transform: "return x - first;"

A gas meter reading 2200, 2210, 2225, 2240 becomes 0, 10, 25, 40.

Splitting a sensor into export/import

A common use case: a single power sensor reports positive values for export and negative values for import. Use two entity entries with different transforms to separate them:

entities:
  - entity: sensor.grid_power
    name: "Grid Export"
    color: "#2ecc71"
    value_transform: "return x > 0 ? x : 0"

  - entity: sensor.grid_power
    name: "Grid Import"
    color: "#e74c3c"
    value_transform: "return x < 0 ? -x : 0"

Common expressions

Time variables (new in v4.04)

Besides the value variables, the expression also receives four read-only time variables:

They make a per-entity time filter possible without a template entity — pair them with return … : null to draw a series only over the part of the X axis you want.

If your expression declares its own t, now, hour or weekday (with var, let or const), the card compiles it without the time variables so your own names keep working exactly as before.

Editor

Entity → Advanced tab → Advanced Calculations → Value Transform — a monospace text input field. Enter the expression directly (e.g., return x - first).

Notes

• The expression must be valid JavaScript and include a return statement
• Returning null leaves a visible gap at that point: the line breaks there rather than joining across the hole, and the tooltip, moving averages and range band all respect it. An expression that throws or returns a non-number does the same (changed in v4.04 — these points used to be removed, which let the line connect straight over them)
• Applied to every data point individually — both historical and live values
• Works with all chart modes, aggregation functions, and other entity options
• Context variables (first, min, etc.) are only available when processing a full data series — in the state row live value display, all context variables equal x

Multiply a series by the value of another entity over time — turn a kWh consumption chart into a money chart using a dynamic price sensor (Nordpool, EPEX, Tibber, a utility tariff helper). Per-entity price_entity needs no template sensor and no duplicate entity: the card bills the consumption itself.

type: custom:statistics-graph-chart-card
card_header: Energy Cost
hours_to_show: 168
group_by: date
entities:
  - entity: sensor.energy_meter
    name: Cost
    graph_type: bar
    aggregate_func: change
    price_entity: sensor.electricity_price
    unit: "€"
    decimals: 2

How it works

• The price is read as a step function from the price entity's own history — each price is valid from the moment it was recorded until the next change. Long windows automatically use long-term statistics (hourly mean) for the price series.
• The multiplication happens per consumption slice, before bucketing — every slice of consumption is billed at the price that was active at that moment, so each bucket is the exact sum Σ(valueᵢ × priceᵢ).
• Designed for aggregate_func: change on cumulative energy counters — set unit to your currency so the state row, tooltip, and axis all read as money.
• price_attribute reads an attribute of the price entity instead of its state — dot notation is supported for nested paths (e.g. raw_today.0.value).
• A state change of the tariff entity auto-refreshes the card, so a price update redraws the cost immediately.
• Period Comparison ghosts are billed at their own period's prices — last week's ghost uses last week's tariffs, keeping the comparison honest.
• Not applied to fixed_value or data_attribute entities.

Why a step function beats average × total

Multiplying the period's total consumption by the average price is only correct when consumption is flat. With time-of-use tariffs the expensive hours tend to be exactly the high-consumption hours, so average × total systematically misstates the bill. Billing every slice at its own momentary price reproduces what the utility actually charges.

Editor

Entity → Advanced tab → Advanced Calculations → Price Entity and Price Attribute inputs.

Plot the combination of two entities — most often their difference — without creating a template sensor. ref_entity names the second entity and ref_op says how to combine them:

type: custom:statistics-graph-chart-card
hours_to_show: 24
entities:
  # indoor − outdoor, the classic delta. ref_op defaults to subtract,
  # and with no name: the series is labelled "Indoor − Outdoor" automatically.
  - entity: sensor.indoor_temperature
    ref_entity: sensor.outdoor_temperature

  - entity: sensor.solar_production
    name: Net export
    ref_entity: sensor.house_consumption
    ref_op: subtract

  # the reference can come from an attribute (e.g. a weather entity)
  - entity: sensor.pool_temperature
    ref_entity: weather.home
    ref_attribute: temperature
    ref_op: divide

How it works

The reference entity's own history is fetched alongside your data and read as a step function: every sample of the main entity is combined with the reference value that was valid at that moment. The math runs before bucketing, so avg over a bucket is the average of the difference, and min/max are the smallest/largest instantaneous gap — not min(A) − min(B). With a delta aggregation (change, diff, sum, delta), subtract / add / reverse_subtract (v4.03) and divide / reverse_divide by a meter (v4.07) combine the two entities per bucket instead — see below.

Rules worth knowing

• Reversed operators. reverse_subtract gives B − A and reverse_divide gives B ÷ A. This is not the same as swapping the two entity ids: the main entity supplies the timeline the reference is sampled onto, plus the unit, aggregation, data source, colour and offset. Keep the better-sampled sensor as entity: and flip the arithmetic instead (e.g. COP = heat ÷ power while power stays the main series).

• subtract / add / reverse_subtract combine levels — or, with a delta aggregation, whole buckets. With avg, min, max, last, first or median the reference is sampled at each of the main entity's readings. With change, diff, sum or delta (v4.03) the two entities are first aggregated the same way, then combined per bucket — the way to add two daily-production meters into one monthly total:

  entities:
    - entity: sensor.goodwe_today_s_pv_generation
      name: Total production
      ref_entity: sensor.solaredge_production_today
      ref_op: add
      aggregate_func: sum
      graph_type: bar
  group_by: month
  

  A bucket in which one side has no data counts that side as 0, so a month with only one inverter reporting still shows the other's production; price_entity is applied to both sides. The bucket-wise path needs an entity: series in a bucketed chart — a statistic_id-only or attribute series still renders empty with a console warning. multiply, and divide by a level (a constant, an input_number, a price, a measurement sensor), are allowed with every aggregation — that is exactly what price_entity does.

• divide / reverse_divide by a meter — total ÷ total per bucket. (v4.07) When the reference is a meter — its state_class is total or total_increasing (energy, gas, water) — and the aggregation is change, diff, sum or delta, both entities are first aggregated the same way and then divided per bucket. A heat pump's daily COP is the day's heat output ÷ the day's electricity:

  entities:
    - entity: sensor.heat_pump_energy_output_heating
      name: COP
      ref_entity: sensor.heat_pump_electricity_used_heating
      ref_op: divide
      aggregate_func: change
      group_by: date
      unit: COP
  

  A bucket where the divisor is 0 or has no data stays empty instead of showing an infinite ratio, a bucket where only the divisor has data shows 0, and a reference with no data at all leaves the series empty. By default the state row shows the newest bucket, so with group_by: date it reads today's ratio so far. Pie, radial bar, polar area, radar, ranking and waterfall charts, the heatmap and calendar cells and the state row's pct share divide the totals of the whole window or cell the same way, so a week of daily COPs reads the week's COP instead of the sum of seven ratios; a bucket that stays empty because its divisor is 0 counts on neither side. price_entity multiplies the main entity only (pricing both sides would cancel it out) — put the priced meter as entity: and use divide: electricity with a tariff ÷ heat is the cost of one kWh of heat. The bucket-wise limits above apply here too. A reference that is a level — a constant, an input_number, a measurement sensor or any ref_attribute — keeps the sample-by-sample rule (energy ÷ floor area), and multiply always combines sample by sample.

• Carry-forward, but nothing invented. The reference is held until it next changes — the same rule Home Assistant itself uses for a state, and the same one price_entity follows. That is what makes a step-shaped reference (a setpoint, an input_number, a mode) work. What the card will not do is invent a value before the reference's first sample: that stretch is a gap. Since the card carries values across gaps by default, a reference that dies mid-window shows as a flat line — add break_on_null: true if you would rather the line break there.

• Both operands should share a unit for subtract/add; the result keeps the main entity's unit. For multiply/divide set unit yourself.

• value_factor and invert apply to the main entity only, before the combination.

• The state row and the trend arrow follow the combined series, not the bare main entity.

• Not available on data_attribute (forecast-array) or fixed_value rows.

• Only one reference and one operator per entity. For multi-operand formulas (A − B − C) you still need a template sensor — a general cross-entity expression is planned for a later release.

Note: data_value_expression + data_vars do not do this. They only apply to an attribute-array data source, and data_vars resolves each name to the referenced entity's current state — a constant, not a series. Use ref_entity for math against another entity over time.

Editor: Entity → Advanced → Reference Entity, Operation, Reference Attribute.

The Range Band feature draws a shaded min/max area behind each line entity, showing how much the value fluctuated within each aggregation bucket.

How it works

When points_per_hour aggregates multiple raw data points into a single graph point, the displayed value is typically the average (or whichever aggregate_func you've chosen). The range band shows the full min → max spread of raw values that were combined — so you can see both the trend and the volatility.

entities:
  - entity: sensor.outdoor_temperature
    show_range_band: true
    color: "#ff4757"
  - entity: sensor.indoor_temperature
    show_range_band: false
    color: "#378ADD"

Use cases

• Temperature: narrow band = stable climate, wide band = fluctuating (e.g. HVAC cycling)
• Energy: see consumption spikes vs steady draw within each time bucket
• Sensor noise: distinguish real signal changes from noisy sensor readings

Editor

Entity → Graph tab → Line section → Range Band toggle (next to Data Points). Timeline mode only.

Tooltip

When hovering, an additional row shows the range: Range: 21.2 → 22.8 °C.

Overlay one or more simple moving-average (SMA) lines on top of any entity — a smoothed trend line that averages the last N buckets. Add as many as you like, each with its own period, color, and width. Perfect for separating signal from noise on busy sensors (CPU load, power, prices) or for classic short/long crossover views (e.g. MA7 vs MA26).

entities:
  - entity: sensor.keenetic_router_cpu_load
    graph_type: bar
    moving_averages:
      - period: 7          # short MA — averages the last 7 buckets
        color: "#ffffff"
        show_label: true   # draw a small "MA7" tag on the line
      - period: 26         # long MA — averages the last 26 buckets
        color: "#f1c40f"
        width: 2           # optional line thickness (px)
        show_label: true   # draw "MA26"

The period is in buckets, not hours

Each line's period is a number of buckets, and the bucket size comes from the chart's timeframe — points_per_hour in interval mode, or group_by (hour / date / week / month / year). So with group_by: hour, period: 26 averages the last 26 hourly buckets (MA26). With points_per_hour: 12 (one bucket every 5 minutes), period: 26 covers the last ~130 minutes.

Automatic look-back — long MAs draw on short windows

A 26-bucket average normally needs 26 buckets of history before it can produce its first value. If your visible window only holds a handful of buckets (e.g. hours_to_show: 24 with group_by: hour → 24 buckets), a plain MA26 would never have enough data to draw.

This card solves that by extending the history fetch backward automatically by the amount the longest moving average needs — independent of the visible window. The MA is computed over that extended range and then trimmed to the window, so MA26 draws fully across a 24-hour view without you having to widen hours_to_show or scroll. The visible chart, axis, statistics, and extrema are unchanged — only the moving-average lines use the extra look-back.

The look-back applies to entities whose data comes from History or long-term statistics. Synthetic sources (fixed_value, data_attribute) average only what's in the window.

Candlesticks

When the entity is drawn as candlesticks, each moving average uses the close of every candle (otherwise it averages the bucket value), so an MA over candles behaves like the moving averages on a trading chart.

Line labels

Turn on show_label for any line to draw a small MA7, MA26 … tag right at the end of that line, so you can tell several averages apart at a glance:

    moving_averages:
      - period: 7
        color: "#ffffff"
        show_label: true

By default the label text is the period prefixed with MA (MA7, MA26, …). (v4.07) Give the item a name to print your own text instead — so a weekly average on hourly buckets reads Weekly trend rather than MA168:

    moving_averages:
      - period: 168
        show_label: true
        name: "Weekly trend"

name only changes the wording: show_label still decides whether a label is drawn, so a name without show_label: true draws nothing, a blank name falls back to MA<period>, and a short name reads best. Whatever the text, the label is drawn at the end of the line and clamped inside the chart, so it never spills outside the plot, with a subtle background halo so it stays readable over the line and the data. It's off by default — flip the Label switch next to the color picker, or set show_label: true in YAML.

Notes

• Each moving average is plotted against the entity's own Y axis, so it lines up with the bars / line / candles it summarizes.
• Lines render in their configured color; leave color empty to fall back to a default. width defaults to a thin line.
• Timeline mode only.

Editor

Per-entity → Graph tab → Moving Averages (just below the Graph card). Click Add Moving Average to add a line, set its Period and Color, flip Label to print an MA7-style tag on the line, type a Name (v4.07) to replace that tag with your own text (the field's placeholder shows the automatic MA<period> text; leave it empty to keep it), and use the ✕ button to remove one.

When a sensor goes unavailable or unknown, the card normally keeps the line continuous by carrying the last known value forward across the gap. That's great for short blips (brief WiFi drops, bucket-level reporting irregularity) but can hide genuine multi-hour outages behind a flat line. The per-entity break_on_null option lets you opt in to a visible break instead.

entities:
  - entity: sensor.steady_sensor
    # default — continuous line, last known value carried across any gap

  - entity: sensor.flakey_sensor
    break_on_null: true
    # short blips still connect, but longer outages appear as gaps

  - entity: sensor.very_specific
    break_on_null: true
    carry_forward_ms: 900000   # advanced — 15 min threshold

Behavior

Why not just "break at every null"?

A pure "zero carry-forward" mode turns out to be too aggressive on real-world sensors. When bucket width is finer than the sensor's natural sample interval (a common setup at high points_per_hour), dozens of buckets between two real samples end up empty even though the sensor is perfectly healthy. The time-based threshold distinguishes "I'm waiting for the next sample" from "the device has been gone for a while" — which is the distinction users actually want to see.

Editor

Entity → Graph tab → Graph section → Break on Gaps toggle (next to Show Average and Data Labels). Shown in every chart mode — carry-forward affects the bucketed data, so it matters wherever those buckets are drawn.

Notes

• Changed in v3.25 — an empty bucket now carries the previous bucket's last recorded sample (its exit state) forward, not the previous bucket's aggregated value. With aggregate_func: first or max, a momentary spike no longer smears across the quiet buckets that follow it; with avg, the carried value is the last actual reading instead of the previous bucket's average.
• Does not affect value_transform scripts that return null — those buckets are already null before carry-forward logic runs, so they stay a visible gap either way.
• Works independently per entity, so you can mix well-behaved sensors (continuous line) with flakey ones (visible gaps) on the same card.

Read chart data directly from an entity attribute instead of history. The attribute must contain an array of objects with time and value fields. The X-axis automatically extends into the future when data contains future timestamps.

Ideal for energy spot prices, weather forecasts, and solar production predictions. No history or statistics API calls are made for these entities.

entities:
  - entity: sensor.epex_spot_price
    data_attribute: data
    data_time_field: start_time
    data_value_field: price_per_kwh
    value_factor: 2
    graph_type: step
    name: "Electricity Price"

Common configurations:

Not every forecast integration exposes an array. Core Forecast.Solar has no attributes at all — its forecast reaches only the Energy dashboard (energy/solar_forecast). Open-Meteo Solar Forecast (HACS) exposes per-day wh_period dictionaries (energy_production_today, _tomorrow, _d2 … _d7), which are not arrays; merge them into one list with a template sensor ([{ start, wh }, …]) and point data_attribute at that. Or skip all of that: solar_forecast: true on a row draws the Energy dashboard's solar forecast directly — see Energy Dashboard Solar Forecast below.

Compatible with existing value_factor, value_transform, aggregate_func, and group_by. The calendar group_by modes (hour, date, week, month, year) regroup the array when the requested cell is coarser than its native spacing — 96 quarter-hourly prices under group_by: hour become 24 hourly values combined with aggregate_func — and pass it through untouched otherwise, so an already-hourly array stays as published. interval (the default) and raw never regroup; the fixed 2h–12h modes are not supported for attribute arrays. points_per_hour does not apply — it controls fetching, and an attribute source fetches nothing. The time and value field names support nested paths via dot notation (e.g. forecast.0.temperature or integrated.0.value).

Computed Values

Sometimes the value you want isn't a single field — you need to combine several fields from each element, fold in other entities (fees, tax rates, tariffs), and apply a formula. Set data_value_expression instead of data_value_field: a small arithmetic expression evaluated for every array element, with the element's own fields in scope plus any names you map in data_vars.

entities:
  - entity: sensor.tibber_hourly_cost
    name: Electricity
    graph_type: bar
    data_attribute: nodes
    data_time_field: from
    data_time_unit: iso
    data_value_expression: "(unitPrice - unitPriceVAT) * 100 * consumption * (1 + mwst)"
    data_vars:
      mwst: input_number.vat_rate

data_vars maps a name to an entity ID; each resolves to that entity's numeric state and is re-evaluated live when it changes. Inside the expression you can use:

This is not JavaScript — there are no other variables, no property access, and no calls beyond those functions, so it can't run arbitrary code. If the expression is empty or fails to parse, the entity falls back to data_value_field.

Elements without a value (v4.08) — an array element that lacks the value field (or holds text that isn't a number) has no reading, so it draws no point: a bar is simply missing, and a line, area or step joins its neighbours — with line_shape: hv the last value is held until the next element. When a missing field means zero — a solar or charging plan that only lists the quarters with energy, for example — wrap the field in coalesce, which returns its first argument that is a number:

    data_attribute: plan
    data_time_field: tijd
    data_value_expression: "coalesce(zon_laden_kwh, 0)"

coalesce takes any number of arguments, so coalesce(override, price, 0) falls through a chain of fields, and it treats a division by zero or a data_vars entity that is unavailable as empty too. When every argument is empty the element is skipped, as before.

Because each element is evaluated independently, two entities reading the same array with different expressions stack cleanly — e.g. splitting an hourly energy cost into a consumption layer and a fixed-fee layer:

type: custom:statistics-graph-chart-card
stacked: true
group_by: hour
entities:
  - entity: sensor.tibber_hourly_cost
    name: Energy
    graph_type: bar
    data_attribute: nodes
    data_time_field: from
    data_time_unit: iso
    data_value_expression: "(unitPrice - unitPriceVAT) * 100 * consumption * (1 + mwst)"
    data_vars: { mwst: input_number.vat_rate }
  - entity: sensor.tibber_hourly_cost
    name: Fees
    graph_type: bar
    data_attribute: nodes
    data_time_field: from
    data_time_unit: iso
    data_value_expression: "(base/30/24 + grid/24 + meter/24) * (1 + mwst) * 100"
    data_vars:
      base: input_number.base_price_month
      grid: input_number.grid_fee_day
      meter: input_number.meter_fee_day
      mwst: input_number.vat_rate

Editor: Per-entity → Advanced tab → Attribute Data Source → Value Expression field, and Data Vars (one name: entity_id per line).

Time Unit

By default, the time field is parsed as an ISO date string. Set data_time_unit to interpret it differently — perfect for sensors that expose monthly summaries, hourly profiles, day-of-year datasets, or Unix timestamps without generating artificial timestamps.

Example — a sensor exposing monthly yield expectations as [{Month: 1, Expectation: 320}, {Month: 2, Expectation: 489}, ...]:

type: custom:statistics-graph-chart-card
group_by: month
graph_start: year
hours_to_show: 8760
entities:
  - entity: sensor.sma_month_yield_expectation
    data_attribute: Expectation
    data_time_field: Month            # 1..12
    data_value_field: Expectation
    data_time_unit: month_of_year     # interpret as Jan..Dec
    graph_type: bar
    aggregate_func: max

Renders 12 bars labelled Jan–Dec on the X-axis. Tooltip shows the actual month + value. All other features (date picker, group_by, fill, theming) work normally because the parser converts the numeric category into a real Date internally.

Editor: Per-entity → Advanced tab → Attribute Data Source → Time Unit dropdown and Reference Year input

Draw the solar forecast your Energy dashboard already shows — Forecast.Solar, Solcast, Open-Meteo Solar Forecast or any other integration that feeds the dashboard — as a row of this card. No entity, template sensor or attribute array is needed: the card reads the same forecast the Energy dashboard reads (energy/solar_forecast).

entities:
  - solar_forecast: true          # no entity / statistic_id needed
    name: "PV forecast"
    graph_type: line
    line_style: dashed

• What you get: hourly points in kWh (the forecast is energy per hour), as far back as the integration returns them (Open-Meteo keeps about three months of past hours, Forecast.Solar starts today) and as far ahead as it forecasts. aggregate_func defaults to sum and unit to kWh; override either like on any row (unit: W + value_factor: 3 plots the hourly mean power — an hourly Wh value is numerically the mean W of that hour).
• Sources: by default every solar source of the Energy dashboard that has a forecast configured is summed per hour, the way the dashboard draws it. solar_forecast_source: sensor.pv_a_energy (the source's energy-production statistic) draws one source only. The row is named after the source (Energy dashboard name or friendly name + " forecast"), or Solar forecast; name: overrides as usual.
• Daily totals: group_by: date (or week / month) sums the hours into calendar cells — the right view for a week or month card.
• Window: the row follows the card window like an attribute source. A rolling window (hours_to_show) is stretched to the last forecast hour — about 16 days ahead with Open-Meteo. graph_start: day|week|month ends at now unless you add show_full_period: true, which shows the whole period including the hours ahead. With energy_date_sync or the built-in date picker the current period also ends at now and is then stretched to the last forecast hour; add show_full_period: true to stay on the selected period (today, this week, this month) with the forecast clipped to it. Past periods show the past hours the integration returns. auto_scale_points steps aside for a solar forecast row, exactly as it does for data_attribute.
• State row: shows the forecast of the current hour (today's total under group_by: date); primary_state_as: sum shows the total of the window, last the last forecast hour.
• Nothing to draw? If the Energy dashboard is not configured, no solar source has a forecast, or the forecast integration is not loaded, the row stays empty, one warning is written to the browser console and the detail legend notes it. The forecast refreshes with the card's periodic poll (every 5 minutes, 15 with a calendar group_by) or with update_interval.

Day view — hourly forecast next to the real production:

type: custom:statistics-graph-chart-card
graph_start: day
show_full_period: true
show_legend: true
entities:
  - entity: sensor.pv_energy_today
    aggregate_func: change
    graph_type: bar
    unit: kWh
  - solar_forecast: true
    name: Forecast
    graph_type: line
    line_style: dashed

Week view — one bar per day, one source only:

type: custom:statistics-graph-chart-card
graph_start: week
show_full_period: true
group_by: date
entities:
  - solar_forecast: true
    solar_forecast_source: sensor.pv_a_energy
    graph_type: bar

Following the Energy dashboard's own date picker:

type: custom:statistics-graph-chart-card
energy_date_sync: true
show_full_period: true     # stay on the selected period; without it the window ends at now and is stretched to the last forecast hour
group_by: date
entities:
  - solar_forecast: true

Past days: the hours before now are whatever the forecast integration returns today for those hours — not a copy of the forecast that was shown on that day. Use them for context, not for accuracy tracking.

Editor: Per-entity → Advanced tab → Solar Forecast (Energy Dashboard) → Solar Forecast toggle and the Forecast Source dropdown (the dashboard's solar sources that have a forecast, by name; All solar sources is the default). The Entity picker on the General tab is marked optional while the toggle is on; Aggregation shows Sum and the Unit field hints kWh.

Display data from imported statistics that don't have a regular entity in Home Assistant. This covers energy data from integrations like Gazpar, Linky, Tibber, and others that import directly into HA's statistics database.

Background

Some HA integrations don't create sensor.* entities. Instead, they write data directly into the statistics and statistics_meta database tables using HA's async_import_statistics() API. These statistics have IDs with a colon separator (e.g. gazpar:gazpar_consumption) and are visible on the Energy dashboard and the built-in Statistics Graph card, but not in the entity registry.

Setup

Use statistic_id instead of (or alongside) entity:

entities:
  - entity: ""
    statistic_id: "gazpar:gazpar_consumption"
    name: "Gas Consumption"
    color: "#f39c12"
    aggregate_func: sum
  - entity: ""
    statistic_id: "linky:linky_consumption"
    name: "Electricity"
    color: "#378ADD"
    aggregate_func: sum
  - entity: sensor.indoor_temperature
    name: "Temperature"
    color: "#ff4757"

You can mix external statistics with regular entities on the same card.

How it works

• The card detects external statistics by checking for a : in the statistic_id
• Data is fetched via HA's recorder/statistics_during_period WebSocket API — the same API the Energy dashboard uses
• Since there is no live state, the state row displays the last known value from the statistics data
• All card features work: tooltip, legend, axes, stacking, offset, zoom, color thresholds, etc.

Editor

Entity → General → Statistic ID input field (monospace, below the entity picker). Set the entity picker to empty and fill in the statistic ID.

Finding your statistic IDs

1. Go to Developer Tools → Statistics in HA
2. Search for the integration name (e.g. "gazpar")
3. The statistic ID is shown in the list (e.g. gazpar:gazpar_consumption)

In Home Assistant's Sections view the card now reports proper grid sizing — the "does not fully support resizing" warning is gone, and you can resize it from the card's Layout tab.

By default height is a fixed pixel value (150). Set it to auto to make the chart fill the grid cell it is given instead:

type: custom:statistics-graph-chart-card
height: auto          # fill the cell; size the card from the Layout tab
entities:
  - entity: sensor.power

Behavior

• A numeric height (e.g. 300) still pins the graph to that many pixels, exactly as before.
• With height: auto the chart grows and shrinks to match the grid cell — drag the card's resize handle (or set grid_options rows) in the Layout tab. Handy for lining a chart up with a neighbouring card's height.
• In a Panel view (v4.03) a timeline chart (the default lines/bars/areas mode) with height: auto fills the whole view on its own — no grid_options needed — and follows the browser window in both directions, shrinking as well as growing. Other chart modes keep their natural size in a panel unless you give them grid_options rows.
• In a Masonry view, or inside a stack card, nothing gives the card a height to fill, so height: auto falls back to a 200 px chart. Use a numeric height there.

Editor

The Height field accepts a number or the word auto. Leaving it empty is treated as auto.

Render axis values as durations or with a custom template instead of plain numbers. The format follows the entity everywhere: axis ticks, tooltips, data labels, the state row and the average-line label.

Duration shorthands

y2_axis_format: h:mm    # 5400 → 1:30
duration_unit: s        # raw unit: s (default) / ms / min / h

Templates

y_axis_format: "{fixed(value/1000,1)} kW"     # 2350 → 2.4 kW
y2_axis_format: "{floor(value/3600)}:{pad2(floor(value%3600/60))}"

Templates accept numbers, value, + - * / %, parentheses and the functions floor, ceil, round, abs, min, max, sqrt, pad2(x), pad(x,width), fixed(x,decimals). No JavaScript is executed — invalid formats are simply ignored and the axis falls back to plain numbers.

Editor

General Settings → Y Axis → Labels → Y Tick Format / Y2 Tick Format / Duration Unit.

The primary (left) and secondary (right) Y axis labels can be toggled independently:

show_y_axis: true       # primary — left side
show_y2_axis: false     # secondary — right side hidden
entities:
  - entity: sensor.temperature
    y_axis: primary
  - entity: sensor.humidity
    y_axis: secondary     # still plotted, just no labels on right

Useful when the secondary axis labels are distracting or when you want to maximize horizontal graph space. Both entities continue to be plotted against their respective axes — only the labels are hidden.

Overlay sensors with completely different units on a single graph for trend comparison. Each independent entity gets its own hidden scale based on its data's min/max range. No axis labels are shown — only the visual trend matters.

entities:
  - entity: sensor.temperature
    y_axis: primary          # Left axis, shared scale, visible labels
    color: "#ff4757"
  - entity: sensor.humidity
    y_axis: secondary        # Right axis, shared scale, visible labels
    color: "#378ADD"
  - entity: sensor.illuminance
    y_axis: independent      # Own hidden scale: 0–10000 lux
    color: "#f39c12"
  - entity: sensor.pressure
    y_axis: independent      # Own hidden scale: 980–1020 hPa
    color: "#2ecc71"

There is no limit on the number of independent entities. Each one is scaled individually. Primary and secondary entities continue to share their respective axis scales.

Editor: Per-entity → Basic tab → Y Axis dropdown → "Independent"

Card-level stacked: true stacks entities on top of each other (Timeline mode only). Bar entities stack vertically. Line/area entities stack as bands. Entities on the same Y axis and graph type are stacked together. The tooltip shows a "Total" row.

stacked: true
entities:
  - entity: sensor.solar_production
    color: "#f39c12"
  - entity: sensor.grid_import
    color: "#e74c3c"
  - entity: sensor.battery_discharge
    color: "#3498db"

Mixing stacked and unstacked entities (v4.07)

The card-level toggle is only the default — each entity can override it with its own stacked. stacked: false on a stacked card takes that entity out of every stack: it is drawn exactly as on a card that is not stacked (a plain line or area, or a bar from the zero line in a slot of its own beside the stacked columns), it keeps its own Y range instead of the stack total, and its data labels sit above the bar again. The classic case is room temperatures as plain lines on the primary axis next to valve positions stacked as bars on the secondary axis:

stacked: true
show_y2_axis: true
entities:
  - entity: sensor.living_room_temperature
    stacked: false                 # plain line on Y1
  - entity: sensor.bedroom_temperature
    stacked: false
  - entity: sensor.living_room_valve
    graph_type: bar
    y_axis: secondary              # the valves stack on Y2
  - entity: sensor.bedroom_valve
    graph_type: bar
    y_axis: secondary
  - entity: sensor.bathroom_valve
    graph_type: bar
    y_axis: secondary

The inverse works too: on a card without stacked: true, the entities that set stacked: true stack with each other (grouped by stack_group, y_axis, graph_type, group_by and invert as always) while everything else stays as it is:

entities:
  - entity: sensor.living_room_temperature   # plain line
  - entity: sensor.living_room_valve
    graph_type: bar
    y_axis: secondary
    stacked: true                             # these three stack
  - entity: sensor.bedroom_valve
    graph_type: bar
    y_axis: secondary
    stacked: true
  - entity: sensor.bathroom_valve
    graph_type: bar
    y_axis: secondary
    stacked: true

An unset entity stacked follows the card, so existing cards look exactly as before. stack_group still only names the group — on its own, without the card's or the entity's stacked: true, it does nothing. Comparison ghosts inherit their main entity's setting, the tooltip's per-group totals only add up the entities that are actually stacked, and the grand Total keeps adding up every visible entity. The key accepts a {{ }} template like the card-level switch.

Stacked Groups

By default, all bar entities stack into a single column. Use stack_group to create named groups — entities within the same group stack on top of each other, while different groups sit side by side.

stacked: true
group_by: date
entities:
  - entity: sensor.solar_production
    graph_type: bar
    stack_group: energy
    color: "#2ecc71"
  - entity: sensor.grid_import
    graph_type: bar
    stack_group: energy
    color: "#e74c3c"
  - entity: sensor.cost_peak
    graph_type: bar
    stack_group: cost
    color: "#f39c12"
  - entity: sensor.cost_offpeak
    graph_type: bar
    stack_group: cost
    color: "#3498db"

This renders two side-by-side bar groups per time slot: an "energy" stack (solar + grid) and a "cost" stack (peak + off-peak). Backward compatible — if no stack_group is set, all entities stack together as before.

Per-group tooltip totals. With tooltip_stacked_total: true (the default), the tooltip shows a separate total for each named group — labelled with the group name (e.g. "energy Total", "cost Total") — so you can read each stack's sum at a glance. It is independent of show_tooltip_total: leave both on to show the per-group totals together with the grand Total of all entities, or turn either one off to show only the other. The per-group rows appear only when there are two or more stack groups; ungrouped entities roll into the grand Total.

Editor: Per-entity → Graph tab → Stacked dropdown (Inherit / On / Off) (v4.07), with the Stack Group text field next to it (shown while the entity is stacked: the card's Stacked toggle on and Inherit, or the dropdown set to On)

Chart pages — several charts in one card (v4.08)

One card, several charts. Give entities a graph_group and the card draws every group on a page of its own — entities that share a name are drawn together, entities without one stay on the main page — with a small strip directly under the graph to switch between them: a dot per page, with ‹ and › right beside the dots. Three temperature sensors in a Climate group next to an ungrouped power sensor make two pages: the power bars on the main page, the three temperatures on the Climate page.

type: custom:statistics-graph-chart-card
card_header: Living Room
hours_to_show: 24
entities:
  - entity: sensor.house_power              # no graph_group → the main page
    graph_type: bar
  - entity: sensor.living_room_temperature
    graph_group: Climate                    # these three share the "Climate" page
  - entity: sensor.bedroom_temperature
    graph_group: Climate
  - entity: sensor.kitchen_temperature
    graph_group: Climate

How the pages come together:

• The main page holds every entity without a graph_group (or with an empty one). The strip shows no names — only a dot per page; hover a dot (or let a screen reader read it) for the group name, Page N for the main page.
• Order follows the first appearance in entities — the dots run in that order. The card opens on the first page — the page of the first entity in the list, so put an ungrouped entity first to open on the main page. Spelling counts: Climate and climate are two pages; spaces around the name are ignored.
• Switching is done with the strip: click or tap ‹ or › (they stop at the first and last page), click or tap a dot, or focus a dot and press Enter or Space. The dots and the two arrows form one compact group in the middle of the strip, so nothing moves as you page through, whatever the group names. Pages turn only from the strip — dragging inside the plot zooms, as on every other card, and the touch gestures (tooltip, long-press zoom, pinch, pan of a zoomed chart) work as usual. The card remembers the page you picked until the dashboard is reloaded.
• Legend and state row. The compact legend, the per-entity statistics legend and the state rows list the entities of the page on screen — turning the page swaps the live values along with the chart. When the pages hold different numbers of entities, the number of state rows, and with it the height of the card, changes from page to page.
• Shared by every page: the date, interval and resolution pickers, zoom and pan, crosshair pins, the scroll position, card-level bounds and annotations, tooltip / zoom / scroll sync. Switching pages only changes what is drawn — nothing is fetched again.
• Export. CSV writes every entity of every page; the chart PNG is the page on screen; the card PNG leaves the page indicator out.
• Every chart mode. Pages work on a Timeline card as on a pie, ranking, gauge, heatmap or state timeline — each page draws the chart of its own entities (heatmap and calendar draw their first entity, so a page per entity gives one heatmap per page) — and on a sparkline card, where the page strip sits under the rows.
• A card where no entity sets graph_group is exactly as before: no indicator, nothing else changes.

Good to know:

• All pages share one chart_mode, one height and the card-level Y bounds — a page cannot have a chart type or size of its own.
• The page strip is about 20 px tall and sits directly under the plot, never over the x-axis dates: ‹, a dot per page and › as one group in the middle. With a numeric height a paged card is therefore about 22 px taller than the same card without pages; with height: auto in a Sections grid or a Panel view the card keeps the size of its cell and the plot gives up that strip instead.
• Entities on different pages are never drawn together, so they cannot stack: stack_group only arranges the stacks within a page. Comparison ghosts, moving averages, ref_entity results and other series derived from an entity stay on that entity's page.
• Not templatable — {{ }} is not evaluated in a group name.

Editor: Per-entity → Graph tab → Graph Group text field, right under Stacked / Stack Group, in every chart mode. Leave it empty to keep the entity on the main page — an empty field writes no YAML.

Per-entity invert: true draws bars downward from the zero line. Tooltip, state row, and extrema labels show positive values. Combined with stacked: true, creates butterfly charts for energy import/export, network in/out, and similar comparisons.

stacked: true
entities:
  - entity: sensor.grid_import
    graph_type: bar
    aggregate_func: change
    color: "#f39c12"
    name: Import
  - entity: sensor.grid_export
    graph_type: bar
    aggregate_func: change
    invert: true
    color: "#3498db"
    name: Export

Inverted entities automatically form their own stacking group — normal bars stack upward from zero, inverted bars stack downward independently. The Y-axis expands symmetrically to accommodate both directions.

When used with line or area charts (not just bars), the fill correctly stops at the zero baseline: mirrored lines fill upward to zero, normal lines fill downward to zero, and series that cross zero get a clean positive/negative split.

invert flips the sign of the value in the shared data pipeline, so it is not timeline-only: in Waterfall it turns the entity into a subtraction step (see Waterfall), and it applies in every other chart mode too.

Editor: Per-entity → Advanced tab → Invert (Mirror) checkbox (next to Fixed Value)

Print the numeric value of every visible data point right above its bar / line / point — the same kind of inline annotation ApexCharts calls dataLabels. Useful when you want the chart to be readable at a glance without forcing the viewer to hover for every value.

entities:
  - entity: sensor.solar_production_today
    graph_type: bar
    aggregate_func: change
    show_data_labels: true
    decimals: 1
    color: "#f1c40f"

How it works

• Labels render above each point, in the entity's color, with a card-background halo so they stay readable over crowded areas. On a stacked: true bar chart each label is centered inside its own segment instead, in white or dark text — whichever stands out against that segment's color — and a segment too short to hold the number shows no label.
• Number formatting follows the entity's own decimals and number_format settings — no separate config.
• For bars, the font size adapts to the available bar width and shrinks down to a minimum of 7 px — it stops shrinking there and the label is still drawn, so on very narrow bars labels can overlap. Use data_labels_font_size to pin a specific size if you'd rather control it yourself.
• For lines / steps, labels anchor to the X position of each data point at a default 10 px.

When to use it

• Bar charts of daily / hourly aggregates where the exact number matters (energy, rain, hours of sunshine)
• Compact summary cards where hover isn't practical (mobile, kiosk displays)
• Reports / screenshots where the chart needs to stand alone without tooltip interaction

When NOT to use it

• High-density line charts — labels will overlap and become illegible
• When you already use show_extrema to highlight just the peaks; the two combined creates visual noise

Editor

Entity → Graph tab → Graph section → Data Labels toggle, sitting next to Show Average and Break on Gaps.

Replace the numeric state row with a half-circle gauge arc. Set show_state: gauge on any entity.

entities:
  - entity: sensor.temperature
    show_state: gauge
    color: "#ff4757"
    lower_bound: 15    # gauge minimum
    upper_bound: 30    # gauge maximum

The gauge arc sweeps 270° from lower_bound to upper_bound. The center shows the current value + unit, bottom edges show min/max labels. Multiple gauge entities display side-by-side: 1 entity = large gauge, 2+ = compact.

color_thresholds work with gauge — the arc color changes dynamically based on value.

The graph below the gauge continues to show the historical trend as usual.

Card-level sparkline: true strips all chrome and renders ultra-compact inline graphs. Only available in Timeline mode.

sparkline: true
entities:
  - entity: sensor.temperature
    color: "#ff4757"
  - entity: sensor.humidity
    color: "#378ADD"
grid_options:
  columns: 12
  rows: 2

Each entity becomes one row: name + value + trend icon on the left, tiny graph on the right. Removed: header, icon, toolbar, axes, grid, tooltip, legend, annotations. Preserved: entity colors, line smoothing, fill, trend icons, live streaming, color thresholds, and rise/fall colors.

Display a battery level indicator on the card. When a header exists (title or icon), the battery appears in the top-right corner. When there's no header, it appears on the right side of the state row.

battery_entity: sensor.temperature_battery
battery_low_threshold: 20

Color adapts to battery level:

The low threshold defaults to 20% and accepts a number, entity ID (sensor.x), or entity attribute (sensor.x.attribute). Hover shows the entity friendly name and exact percentage.

The icon and percentage text scale proportionally with the Header & Battery Size setting (card_header_size). This applies in both header and state row positions.

Editor: General Settings → Overlay tab → Battery

Card-level show_legend: true adds a compact color-coded entity name key below the graph. Just colored dots and names — no values, no stats. Wraps to multiple lines on narrow cards. Every enabled entity is listed, including show_graph: false rows — set show_in_compact_legend: false on an entity to leave it out (v4.07).

show_legend: true
entities:
  - entity: sensor.memory
    name: "Memory"
    color: "#f39c12"
    show_state: false
  - entity: sensor.disk
    name: "Disk"
    color: "#85b7eb"
    show_state: false
  - entity: sensor.cpu
    name: "CPU"
    color: "#00bcd4"
    show_state: false

This produces: ● Memory ● Disk ● CPU in a centered wrapping row below the graph. Combine with show_state: false on entities to maximize graph area while still identifying colors.

For per-entity statistics (Min, Avg, Max, Sum, Last, Live), use the entity-level Legend toggle instead — see Entity Legend Stats.

Each entity's Legend toggle (show_in_legend: true) lets you choose which statistics to display. Select any combination of Min, Avg, Max, Sum, Last and Live.

entities:
  - entity: sensor.temperature
    show_in_legend: true
    legend_stats:
      - avg
      - last
  - entity: sensor.humidity
    show_in_legend: true
    legend_stats:
      - min
      - max

min, avg, max and sum describe the time range currently on screen, and last is the final plotted value in it — so all five move when you change the period or zoom.

live (v3.32) is different: for a normal history-backed entity it is the state right now, independent of the displayed range.

entities:
  - entity: sensor.power
    show_in_legend: true
    legend_stats:
      - avg
      - live      # today's average, next to what the meter reads this second

It goes through the same value pipeline as the state row, so the two agree on what the number means:

• an attribute: entity shows that attribute, not the entity's own state;
• a state_map entity shows its mapped text label;
• invert, value_factor and value_transform are applied;
• with ref_entity it shows the combined value (the A − B your chart draws), and shows — rather than a misleading number if the combination has nothing to report;
• comparison ghost rows never get a Live value — a ghost shares the main entity's ID, so "now" would be printed under a "previous period" heading.

Two deliberate differences from the state row:

• primary_state_as (and the legacy show_state_last) are ignored here. Those pick what the state row displays; the Live chip is always the live reading, so a card with primary_state_as: max shows the max in the header and the current value in the legend.
• Three configurations have no live state to show and fall back to the last value in the fetched window instead: ref_entity (the last point of the combined series), a non-zero offset, and long-term-statistics rows. For those the value is the last value of the loaded period — it changes with the period, not with a zoom.

Otherwise the Live value refreshes as soon as the entity changes, without waiting for the next data refresh.

The editor shows six checkboxes (Min, Avg, Max, Last, Sum, Live) inside the Legend section. Default is [min, avg, max] for backward compatibility.

Entity state rows can be placed below the graph instead of above. The align_state option accepts six positions:

entities:
  - entity: sensor.temperature
    align_state: bottom-left
  - entity: sensor.humidity
    align_state: left         # stays above the graph

Mix and match — some entities above, some below. Useful when you want the graph to be the first thing visible, with values underneath.

Click and drag on any Timeline mode graph to zoom into a specific time range. No configuration needed — it's always available.

How it works

1. Click and drag horizontally — a blue selection overlay appears with formatted timestamps at both edges
2. Release — the graph zooms into the selected range: the Y axis and grid rescale to the data in view, the legend statistics (show_in_legend — Min, Avg, Max, Sum, Last) are recalculated from the points inside that range, and show_extrema labels move to the lowest and highest point in view. The state row and the legend's live value are not range statistics: they keep showing the whole-period figure and the current state
3. Step back — double-click the graph (double-tap on mobile) to step back one zoom level (see Zoom History). Keep double-clicking to unwind every level and return to the full window

Key details:

• Instant zoom — zooming never re-fetches data from Home Assistant; zoom and reset are immediate.
• Progressive zoom — zoom again within an already-zoomed view to drill deeper into spikes or anomalies
• Touch support — works on mobile: long-press, then drag to select; once zoomed, a one-finger drag pans the window
• Minimum 15px selection — prevents accidental zoom from regular clicks or taps
• Time formatting — selection labels show time only for ranges under 24H, date + time for longer ranges
• Picker aware — changing the period via the interval picker or the date picker resets any active zoom and fetches fresh data

Zoom Buttons (new in v4.04)

Set show_zoom_buttons: true to put small zoom in, zoom out and reset buttons in the top-right corner of the chart, next to the export icon if you use one.

type: custom:statistics-graph-chart-card
show_zoom_buttons: true
hours_to_show: 168
entities:
  - entity: sensor.power

• Each click halves or doubles the visible range around its centre, down to a one-minute floor
• Reset appears only when there is something to reset — once you have zoomed or drilled in — and returns the chart to its full window in one click, unwinding Drill Down levels too
• Independent of the drag brush — they still work with brush_zoom: false, which is the point on touch screens where the brush needs a long press first
• Grouped cards follow through Zoom Sync, exactly as a brush zoom does
• Off by default, Timeline mode only, and hidden in sparkline and controller cards

Zooming is a view transform. It stretches the points already fetched and never asks Home Assistant for finer data, so zooming a 24-hour window down to one hour shows the same points spread wider. Use Drill Down when you want the card to re-fetch at a finer resolution.

Pinch Zoom (touch) (new in v3.25)

On touch devices, a two-finger pinch zooms the timeline directly — no long press needed:

• Spread two fingers to zoom in — the view scales live around the midpoint of the gesture while the fingers move
• Bring them together to zoom back out — zooming all the way out returns to the full window
• Any pinch angle works (improved in v3.26) — the gesture measures the true 2D distance between the fingers, so vertical and diagonal pinches (thumb below, index above — the most natural grip) zoom just like horizontal ones
• Amplified response (improved in v3.26) — zoom follows an amplified (squared) curve, so a small real-world pinch zooms meaningfully instead of barely moving the window; pinching inward zooms out just as strongly
• Double-tap still steps back one zoom level at a time — see Zoom History below
• Available whenever the drag brush is — the same gate applies (Timeline mode, brush zoom not disabled)
• Works with cross-card Zoom Sync: the final window is broadcast once at gesture end, not continuously during the pinch

Zoom History (new in v3.25)

Every committed zoom — a released brush selection or a finished pinch — pushes the previous window onto a history stack (up to 20 levels):

• Double-click (mouse) or double-tap (touch) steps back one level at a time
• With an empty stack, double-click shows the full window
• The stack resets whenever the data window itself refreshes — date/interval picker changes, the live window sliding forward, or a polling refresh

Changed in v3.25: double-click used to reset the zoom completely in one go. It now steps back one level at a time, so you can retrace a deep zoom instead of losing it all at once. Double-click repeatedly to unwind every level.

No new YAML options — pinch zoom and zoom history are part of the standard brush zoom behavior.

Mouse & Touch Behavior (updated in v4.03)

Mouse (desktop)

• Hover — the tooltip follows the pointer; leaving the graph hides it.
• Click with crosshair: true — pins the crosshair at that time and the tooltip stays. With crosshair_pins: 2 a second click places pin B. Once all pins are placed, a click on empty graph area clears them.
• Press on a pin line (within about 12 px) and drag — moves the pin; no brush zoom starts.
• Press and drag on empty area — brush zoom (a drag shorter than 15 px does nothing).
• Double-click — steps back one zoom level, or drills up when not zoomed. It also undoes whatever its first click did to the pins.
• Right and middle click — ignored.
• drill_down: true — a single click drills down. With crosshair on, the click places a pin instead, so combine drill-down with crosshair: false.
• A zoomed window is not panned with the mouse — a mouse drag is always a brush. Wheel and scroll mode are unchanged.
• Touch-screen Windows devices follow the touch rules below.

Touch (phones, tablets)

Touch gestures separate tooltip exploration from brush zoom:

Holding still for 600ms prepares zoom but does not activate it — zoom only starts when the finger moves. This prevents the tooltip from disappearing while exploring a single data point. In scroll mode (max_visible_interval) a horizontal drag scrolls the chart natively; the pan gesture only applies to a brush or pinch zoom.

What changed in v4.03 (touch)

With crosshair: false (the default) every gesture behaves exactly as before; the only new behaviour is panning a zoomed chart.

A hover tooltip is gone the moment your finger leaves the screen. With crosshair: true a tap (or click) pins a crosshair at that time: the tooltip stays on screen, the pin can be dragged along the graph, and once all pins are placed a tap on empty graph area clears them.

type: custom:statistics-graph-chart-card
crosshair: true
crosshair_pins: 2          # 1 (default) or 2
crosshair_delta: true      # default: Δ rows when two pins are placed
crosshair_legend: true     # optional: pinned values next to the legend entries
entities:
  - entity: sensor.energy_today
  - entity: sensor.power

• One pin — the tooltip shows the values at the pinned time and stays put; hovering or sliding elsewhere no longer moves it. Drag the pin line to move it.
• Two pins (crosshair_pins: 2) — the second tap adds pin B. The tooltip header becomes A → B with the time span between them, every series shows value A → value B, and with crosshair_delta a Δ row gives the change as a value and a percentage (green up, red down). With more than one numeric series a Total A → B row is added (its Δ follows crosshair_delta too). For a cumulative meter that delta is the consumption between the two points. Series that show state labels instead of numbers get no Δ. When a zoom or pan leaves one pin outside the view, that side reads "—" until it is back in view.
• Legend readout (crosshair_legend: true) — the same values appear next to each legend entry, coloured by trend when two pins are set.
• Sync — the pinned time is broadcast through Tooltip Sync, so synced cards show their tooltip at that time; a card with its own pins ignores incoming hover updates.
• Pins are session state: they are not saved, and they clear when the card leaves the page. A pin that falls outside the visible window after a zoom or pan is kept and reappears when the window covers it again; while no pin is in view the hover tooltip works as usual. Pins are not part of PNG exports.
• While crosshair is on, a tap is taken by the pin, so drill_down does not fire on tap (double-click still drills up). Double-tap and double-click undo what their first tap did to the pins, so stepping back a zoom level neither leaves a stray pin behind nor loses the pins you had.

Editor: Overlay tab → Tooltip → Crosshair Pins, then Pins, Pin Delta and Pins in Legend.

Card-level show_export: true overlays a small download icon on the top-right of the card. Clicking it opens a menu — Download PNG (Chart) / Download PNG (Card) / Download CSV — and the menu closes on any outside click.

type: custom:statistics-graph-chart-card
card_header: Energy Overview
show_export: true
entities:
  - entity: sensor.energy_consumption

PNG

• Download PNG (Chart) — a 2× resolution snapshot of the current plot — crisp on high-DPI displays
• Download PNG (Card) — captures the entire card exactly as rendered: header, chart, state row, and legend included
• Works in all chart modes: canvas-rendered modes (Pie, Heatmap, Ranking, …) are copied directly, and the SVG timeline is serialized with the correct axis-label styling and the card background color, so the file looks exactly like the card
• When the active theme paints the card with an external background image, the Card capture falls back to the Chart export — browsers block capturing images that come from another server.

CSV

• Wide format — the first column is time (ISO 8601, UTC), followed by one column per visible series; series hidden via the legend are excluded
• UTF-8 with BOM and CRLF row endings, so the file opens correctly in Excel without an import wizard
• Period Comparison ghosts export as their own suffixed columns, with timestamps shifted into the current window so they align with the main series
• Candlestick series export the bucket value only — no separate OHLC columns

Behavior

• Export what you see — if the chart is zoomed (brush or pinch), both the PNG and the CSV cover exactly the zoomed range
• Filenames combine the sanitized card_header with a timestamp, e.g. Energy_Overview-20260715-1630.png / .csv
• Hidden in sparkline mode
• show_export accepts {{ }} templates — see Template Toggles

Editor

General Settings → Chart → Visual Options → Show Export Button.

Add reference lines, event markers, and highlight bands to the graph (Timeline mode only). Configure via the editor (General Settings → Overlay tab → Annotations) or YAML.

annotations:
  - type: threshold       # horizontal dashed line
    value: 22.5
    label: "Target"
    color: "#1D9E75"
  - type: threshold       # dynamic value from entity
    value: sensor.climate_setpoint
    label: "Setpoint"
    color: "#f39c12"
  - type: band            # horizontal shaded band
    value: 20
    value_end: 23
    label: "Comfort zone"
    color: "#1D9E75"
  - type: band            # dynamic band from entity attributes
    value: sensor.comfort.min_temp
    value_end: sensor.comfort.max_temp
    label: "Dynamic comfort"
    color: "#3498db"
  - type: event           # vertical marker at state transitions
    entity: binary_sensor.heating
    state: "on"
    label: "Heating on"
    color: "#D85A30"
  - type: span            # vertical band for active periods
    entity: binary_sensor.heating
    state: "on"
    color: "#D85A30"