Energy Horizon Card

Elegant energy comparisons for Home Assistant dashboards — cumulative usage now vs a historical reference, with optional forecast.

• Clear comparisons: see “this period so far” vs a reference period at a glance.
• Readable timelines: smart axis labels that stay legible on mobile.
• Always-usable charts: automatic aggregation keeps the chart clean.
• Optional forecast: a dashed estimate for the period total when it’s meaningful.

This card is built for long-term statistics (energy history), not live power charts.

Quick start (copy/paste)

1) Install

• HACS (recommended): HACS → Frontend → Add repository → install Energy Horizon Card → restart Home Assistant.
• Manual: download energy-horizon-card.js from the latest release → copy to config/www/.

2) Add the Lovelace resource

Settings → Dashboards → Resources:

url: /hacsfiles/energy-horizon-card/energy-horizon-card.js
type: module

Manual installs usually use:

url: /local/energy-horizon-card.js
type: module

3) Add the card

type: custom:energy-horizon-card
entity: sensor.your_energy_statistic
comparison_preset: year_over_year

4) If you see an empty chart

Most often, the selected entity has no long-term statistics.

• Check Home Assistant Developer Tools → Statistics.
• Then follow: Troubleshooting and FAQ.

Basic configuration (first knobs to turn)

These are the options most people adjust first. Everything else is in the Wiki and README.advanced.md.

Option	What it does	Learn more
comparison_preset	Pick the comparison: year-over-year / month-over-year / month-over-month.	First Comparisons: Quick Recipes
aggregation	Control the chart resolution (hour/day/week/month) or omit for auto.	How-To: Aggregation & Performance
show_forecast	Show/hide the dashed forecast line.	Forecast and Data Internals
precision	Decimal places for UI numbers.	Configuration and Customization
force_prefix	Unit scaling (auto, none, k, M, …).	Configuration and Customization
primary_color	Current series line/fill color; default is the card’s brand teal (#119894). Use ha-primary or var(--primary-color) to follow your HA theme.	README.advanced.md
show_comparison_summary, show_forecast_total_panel, show_narrative_comment	Hide specific card sections (comparison panel, Forecast | Total panel, narrative comment).	Configuration and Customization
title, icon	Card header customization.	Configuration and Customization

Key features (in plain words)

Smart X-axis (labels that “just make sense”)

The card adjusts date/time labels automatically so they stay readable (especially on phones). With two or more windows, the shared axis length follows the largest nominal slot count at the chart’s aggregation (e.g. February vs March at daily grain uses 31 slots); tick dates follow window 0’s calendar (with an ordinal tail if the axis is longer), and the “now” marker is based on today inside window 0. Forecast progress still uses window 0 only, so the axis can be longer than the forecast period. Tooltip headers use that same slot index and the Home Assistant time zone for calendar text (not the browser’s zone). For YoY/MoY/MoM, adaptive labels drop redundant years or months so the axis matches the comparison story (see wiki mental model). Long-term statistics that expose sum are mapped so each daily (or hourly) increment sits under the correct calendar bucket on that axis; when LTS has only min/max (common for misclassified cumulative templates), increments use max - min. See Forecast and Data Internals and README.advanced.

• Learn more: Aggregation and Axis Labels

Automatic aggregation

If you don’t set aggregation, the card picks a sensible bucket size so you get a clear chart instead of thousands of cramped points.

• Learn more: How-To: Aggregation & Performance

Forecast

When there’s enough data and a valid reference, the dashed line estimates the period total based on your history.

• Learn more: Forecast and Data Internals

Advanced configuration (power users)

Want more control? Start here:

• Custom time windows (time_window):
  • How-to: How-To: Time Windows
  • Reference: Time Window Reference
• Date formatting (Luxon) (x_axis_format, tooltip_format):
  • Reference: Luxon Formats Reference
• Full YAML reference (authoritative):
  • README.advanced.md
  • Wiki: Configuration and Customization

Documentation map

• Wiki Home (Diátaxis map): Energy Horizon Wiki
• Advanced reference: README.advanced.md

Support and releases

• Releases: GitHub Releases
• Issues: GitHub Issues
• Discussions: GitHub Discussions

If this card saves you time, you can support development:

Development

Stack: TypeScript (strict), Lit 3, Apache ECharts 5, Luxon 3 (time windows), Vite 6, Vitest 2.

User-visible strings live in src/translations/ (en.json is the key reference). Use one full sentence per message with {{camelCase}} placeholders for injected values — see specs/002-i18n-localization/.

npm install
npm run build
npm run dev
npm test
npm run lint

License

MIT