A Home Assistant custom card for reusable time-bucket heatmaps across numeric sensors, units, and update frequencies.
The SVG above is a self-contained synthetic demo when opened directly: room tabs, cell hover/click details, and a link to the full local demo harness. README previews may render it as a static image.
This first pass is intentionally focused:
- Numeric single-entity and multi-entity heatmaps.
- Home Assistant recorder statistics via
hass.callWS. - Short-range REST history fallback when statistics are unavailable.
- Canvas rendering for the heatmap body.
- HACS-ready
dist/universal-heatmap-card.jsoutput. - YAML configuration with a graphical editor for common single- and multi-entity setup.
Until this is added to the default HACS store, install it as a custom repository:
- In Home Assistant, open HACS.
- Open the three-dot menu and choose Custom repositories.
- Add
https://github.com/gcs8/universal-heatmap-cardas category Dashboard. - Download Universal Heatmap Card.
- Confirm the dashboard resource points at
/hacsfiles/universal-heatmap-card/universal-heatmap-card.js.
Then refresh the browser and use type: custom:universal-heatmap-card in a dashboard card.
Build the card:
npm ci --ignore-scripts
npm run buildCopy dist/universal-heatmap-card.js into Home Assistant's /config/www/ directory, then add this dashboard resource:
url: /local/universal-heatmap-card.js
type: moduleUse the card:
type: custom:universal-heatmap-card
entity: sensor.living_room_temperature
range:
days: 30
bucket:
interval: day
value: mean
scale:
preset: temperaturetype: custom:universal-heatmap-card
title: Example Power
entities:
- entity: sensor.example_power_a
name: A
- entity: sensor.example_power_b
name: B
- entity: sensor.example_total_power
name: Total
range:
days: 14
align: day
bucket:
interval: hour
value: mean
scale:
min: 0
max: 2500
data:
refresh_interval: 300
defer_until_visible: true
max_concurrent_requests: 2
layout:
bound_to_grid: auto
navigation:
mode: tabsBy default, ranges use fixed local days so hourly columns stay stable from local 00:00 through 23:59. This keeps daily heatmaps visually comparable as the day moves on:
range:
days: 14
align: day # optional, because day is the defaultSet range.align: rolling when the moving "last N hours/days ending now" behavior is preferred:
range:
hours: 24
align: rollingExact YYYY-MM-DD start/end values are interpreted as local midnight. Values that include an explicit time or zone use normal JavaScript timestamp parsing:
range:
start: "2026-05-01"
end: "2026-05-02"Axis tick labels are shown by default. The extra explanatory key is off by default because it is redundant when the graph is already well labeled:
axes:
show: true
x_labels: true
y_labels: true
show_key: falseSet axes.show_key: true when you want the card to explicitly spell out the encoding. Hourly cards use X = time of day and Y = date. The 5-minute interval keeps native 5-minute buckets in 48-column, 4-hour rows: x-axis ticks show elapsed offsets within each row, row labels show the local date and strip start time, and tooltips include local hours and minutes. Daily cards place each day under its weekday column (Monday first) with one row per week, and monthly cards place each month under its calendar-month column with one row per year, so the first row may start with blank cells.
By default, color scales use the observed bucket values in the rendered time window unless you set fixed scale.min or scale.max. With scale.ignore_zero: auto, zero values are excluded from the automatic domain whenever the finite values include both zero and a positive value, with no negatives. This applies regardless of how often zero occurs. Zero-valued cells still render, but clamp to the lowest color and can look the same as the lowest positive value. Set scale.ignore_zero: false to include zeros in the domain. Set it to true to exclude zeros even when negative values are present; negative values remain in the domain. Fixed scale bounds still win.
Scale tuning is optional:
scale:
# > 1 pushes colors farther from the midpoint; < 1 softens contrast.
sensitivity: 1.4
# 2 trims the auto-scale domain to the 2nd through 98th percentiles.
outlier_clip: 2Use sensitivity when close values need more visual separation or noisy/peaky values need less drama. Use outlier_clip when rare spikes should not define the whole color range. Fixed scale.min and scale.max still win when set.
Tile numbers are off by default so dense dashboards stay readable. Enable them when you want compact bucket values drawn inside each cell:
tiles:
show_values: trueAdd an on-card 123 button beside the current value chip when you want to toggle numbers without opening edit mode:
tiles:
show_value_toggle: trueThe card reserves larger preferred cells when values are enabled or when the on-card toggle is available, and hides labels if the card becomes too narrow to keep them legible.
Home Assistant sections dashboards use a 12-column grid with 56px rows and 8px gaps. The card's getGridOptions() reports section rows from an estimated rendered height using that official sizing model. If a dashboard also has saved grid_options.rows, the card treats those rows as a height budget and caps the canvas only while it can keep readable cells instead of pushing into the next section:
layout:
# auto bounds only when grid_options.rows exists.
bound_to_grid: autoSet layout.bound_to_grid: false if you are using grid_options outside a sections dashboard and want the card to keep natural height.
For manually saved wide sections, make the card columns match the section span. A 2-wide section is 24 card-grid columns:
column_span: 2
cards:
- type: custom:universal-heatmap-card
grid_options:
columns: 24Debug logging is off by default. Enable it only while diagnosing a card:
debug: trueYou can also enable it temporarily from the browser console:
localStorage.setItem("universal-heatmap-card:debug", "1");Debug logs report cache hits/stales, provider source, bucket counts, scale bounds, and load/draw timings. They do not print Home Assistant tokens or raw recorder rows, but they may include entity IDs and value ranges.
Run the lightweight render-path proxy harness locally:
npm run perf
npm run perf:stressCI runs npm run ci:guard to block accidental resource hogs such as scheduled workflows, unbounded matrix jobs, missing job timeouts, or npm installs without --ignore-scripts. The perf harness stays manual so push/PR CI remains cheap.
The card caches each rendered entity/range/bucket/scale query for five minutes by default. This keeps normal Home Assistant state updates from repeatedly querying recorder history. The value is a minimum cache age, not a background polling timer:
data:
# Seconds. Set to 0 to cache until the card config changes.
refresh_interval: 300
# Keep off-screen cards from querying recorder until they scroll near view.
defer_until_visible: true
# Shared browser-side cap across all universal heatmap card instances.
max_concurrent_requests: 2- Numeric sensors with recorder statistics are the primary supported data path. The card queries Home Assistant from the browser with
recorder/statistics_during_period. - With recorder statistics,
bucket.value: sumreadschange, the per-bucket total, rather than the recorder's cumulativesum.changealso reads recorderchange;lastreadsstate;mean,min,max, andstateread their matching statistic. - Short raw-history fallback is available for values that are not in recorder statistics, but it is capped by
data.raw_history_hoursto avoid large browser-side history pulls. The default is 24 elapsed hours, not one local calendar day. This cap applies to bothdata.provider: historyand automatic history fallback, and checks the full query window, including any not-yet-elapsed part of a day-aligned range. - A day-aligned local day spans 23 elapsed hours on a spring-forward day, 24 on an ordinary day, and 25 on a fall-back day in zones with a one-hour DST change. A full fall-back day therefore exceeds the default 24-hour raw-history cap and does not query history. Use recorder statistics, shorten the window, or explicitly set
data.raw_history_hours: 25to permit that full day. The card never adds a DST allowance to the configured cap. Rolling ranges count elapsed hours; explicit start/end windows use their actual elapsed duration for the same cap. - Missing modes
zeroandcarry_forwardfill only buckets whose start is before the fetch-time clock reading. Historical gaps and the in-progress bucket retain the selected fill behavior; empty buckets starting exactly at that time or later remain missing. Finite values returned by the provider are preserved even when future-dated. One captured fetch time determines the query window and fill cutoff across delayed statistics/history requests. - With raw history,
sumadds the numeric samples within each bucket. It is not a meter delta and depends on sample frequency. Automatic fallback can therefore change the meaning of asumbucket and reports a warning when statistics are unavailable. For cumulative energy or water meters, usedata.provider: statisticswithbucket.value: sumorchangeto avoid sample-sum fallback. The card uses the recorder's change values as returned, including its reset handling; it does not difference cumulative totals itself. - Dense windows are bounded by
data.max_cells; raise it deliberately if you really want a larger grid. - Wide dashboards are protected by lazy loading and a shared request queue. Off-screen cards wait until they are near the viewport, repeated Home Assistant state updates reuse the in-flight load for the same card, and
data.max_concurrent_requestsdefaults to2. - Multi-entity cards work best when all entities share comparable bucket semantics and units. Per-entity
scaleoverrides are supported. - Binary runtime aggregation is planned, but not ready yet.
percent_onandduration_onare reserved bucket values for that pass. - The graphical editor covers common single- and multi-entity options, including reordered entity lists, entity display aliases, fixed/rolling alignment, scale preset, fixed min/max, sensitivity, outlier clipping, optional tile value labels, and the on-card value toggle. Use YAML mode for custom color stops, per-entity scale overrides, and unusual nested config.
- Compare mode is not included yet.
npm ci --ignore-scripts
npm test
npm run ci:guard
npm run perf
npm run buildRun the local demo harness:
npm run devThen open http://localhost:5173/demo/.
Regenerate the standalone interactive SVG used in this README:
npm run docs:demo-svgThe demo can switch between generated data and a local static Home Assistant export. The real fixture and local sync config are intentionally gitignored.
Create demo/fixtures/local-sync-config.json:
{
"env": "demo/fixtures/homeassistant.env",
"entities": ["sensor.example_power"],
"days": 14,
"sample": {
"enabled": true,
"per_type": 3,
"max_types": 16
}
}Then sync:
npm run sync:ha-fixtureThis writes demo/fixtures/local-real.json. Pinned entities stay as the first local view, and sample.enabled adds random recorder-backed metric views for comparing scale behavior across power, energy, temperature, humidity, battery, pressure, signal quality, voltage, current, distance, duration, and other numeric sensors.
You can also pass entities or sampling options directly:
npm run sync:ha-fixture -- --days 30 --entity sensor.example_power
npm run sync:ha-fixture -- --sample --sample-per-type 4 --sample-max-types 12The HACS plugin file is generated at dist/universal-heatmap-card.js.
CI runs workflow resource guards, unit tests, builds the release bundle, and validates the repository with the official HACS action as a dashboard/plugin repository. Release builds intentionally do not emit source maps. There are no scheduled workflow runs by default, and workflow actions are pinned to reviewed full commit SHAs.
- Confirm
hacs.jsonpoints atdist/universal-heatmap-card.jsand the built file is included in the release. - Confirm
dist/universal-heatmap-card.jsis committed and matchesnpm run build. - Run
npm test,npm run ci:guard,npm run perf,npm run build, andnpm audit --omit optional. - Review pinned GitHub Action SHAs before release bumps; Dependabot is configured to open reviewable action and npm update PRs instead of tracking moving refs.
- Smoke test light theme, dark theme, sections dashboards, masonry dashboards, mobile/narrow widths, edit mode, and the visual editor.
- Scrub screenshots, demo fixtures, and examples for private Home Assistant entity names or local network details before publishing.
Installs are script-disabled by default through .npmrc. Use npm ci --ignore-scripts, keep package-lock.json committed, and review SECURITY.md before adding dependencies.