🚀 Release: v1.3.0

[github-actions[bot]]

🚀 New Release: v1.3.0

View full release and download on GitHub

---

Three new history charts (area, column and combined) and two features every history chart now shares: calendar periods with previous and next buttons, and grouping readings by hour, day, week or month. A meter that counts up can now show its energy per day as columns with no setup beyond the entity. Chartdeck is also now in the HACS default store, so it no longer needs adding as a custom repository. Nothing about your existing cards needs changing: the bar and gauge styles and the line chart draw as before, unless you choose the new options.

Fixed

• Time labels along the bottom of a chart no longer run into each other on narrow cards. The number of labels was worked out from the whole card's width, but the value labels on the left take part of that width. On a narrow card, or with a second value axis, times crowded together ("9:30 AM10:00 AM"). They are now spaced across the plot itself. (#96)

Added

Area chart

• A card can now draw history as a filled area, so an amount reads at a glance. Set style: area (or pick Area under History charts in the Style section). It suits solar through the day, the house's power use, or grid import and export either side of zero. It shares the line chart's period, calendar spans, grouping, statistics, axes, hover readout and compact layout. (#97, closes #10)

  type: custom:chartdeck-card
  style: area
  title: Grid
  stack: none
  entities:
    - entity: sensor.grid_power
      name: Grid
      negative_color: green

  • The fill is a soft gradient, strongest at the top and fading towards zero. Below zero it fades the other way, and the entity's negative_color (in each entity's options as Colour below zero) colours both the fill and the outline there, such as export in green under import in blue.
  • stack: normal piles the series up so the top edge is their total; stack: percent scales every moment to 100 %. The series are compared at every moment any of them changed. Positive values stack up from zero and negative ones down from it, so export never cancels import. The hover readout puts each dot on its own layer, adds a Total row, and in percent mode shows each share.
  • An area whose readings come down near zero stands on zero, rather than on a rounded step below it. Readings far from zero, such as a room at 18–22 °C, keep a fitted axis. y_min and y_max always win.
  • curve (smooth, straight or step), line_width (2 px by default) and dots work on the card or per entity. Gaps where a sensor was unavailable are left in both the fill and the outline.

Column chart

• A card can now draw history as columns, one per hour, day, week or month, and is right with no options. Set style: column (or pick Column under History charts). With nothing else set it shows the last 7 days, one column per day, and each column shows how much the meter rose that day if every entity is a meter (state_class total or total_increasing). Otherwise each column is the day's average. (#98, closes #11)

  type: custom:chartdeck-card
  style: column
  title: Energy per day
  entities:
    - sensor.house_energy

  • group_by: auto (the default) picks a grouping for the span: hours up to two days, days up to two months, then weeks, then months. Today is grouped by hour, a week or a month by day, and a year by month. group_by: none draws one column per reading.
  • Several entities sit side by side in each group. stack: normal piles them into one column and stack: percent scales each column to 100 %. Negative values hang below zero, and the axis always includes zero.
  • labels: true puts each column's value (or a stack's total) on top. Labels are left off when the columns are too narrow, or when there are more than 60. rounded (on by default) rounds the outer ends, and stays round at any card width.
  • range: true draws each column from the group's lowest reading to its highest, with the average marked across it, such as a day's temperature spread. From statistics it asks the recorder for min and max; from history it uses the spread of the values held in each group.
  • color_by: bands colours each column by its value's colour band. An entity's target from the Limits section is drawn across each of its columns.
  • When grouped, the time axis puts one label under each group (Mon, Tue… or 26 Oct, or Oct, Nov), every second or third if they wouldn't all fit. The hover readout names the whole group ("26 Oct – 1 Nov") and highlights it.
  • In the editor: Chart section, with the period (7 days by default), Group readings by (with Automatic and Don't group), Combine with, Stack, Colour, Lowest to highest in each column, Show values on the columns and Rounded tops. Each entity gets its own Colour.

Combined chart

• One chart can now mix lines, columns and areas, with a second value axis for a different unit. Set style: combined and give each entity a type. You might draw daily energy as columns with the day's average temperature as a line, or power as an area with the electricity price as a line. (#99, closes #12)

  type: custom:chartdeck-card
  style: combined
  period:
    last: 14
    unit: day
  entities:
    - entity: sensor.house_energy
      type: column
    - entity: sensor.outside_temperature
      type: line
      y_axis: right

  • type is line (the default), column or area. Areas are drawn at the back, then columns, then lines on top.
  • The first entity's unit goes on the left axis and any other unit on the right, unless an entity's y_axis says left or right. The right axis has its own round steps; gridlines follow the left one, and y_min / y_max fix the left one.
  • With any columns and no group_by, readings are grouped to suit the span, as on the column chart. Every series is drawn at the middle of its group, so a line runs over the columns' centres. Each entity is combined in its own way: a meter's change next to a temperature's average, or the entity's own aggregate. With source: statistics, the card's aggregate applies to all.
  • The hover readout lists every series, with dots on lines and areas placed on their own axis.
  • In the editor, each entity has Draw as, Value axis, Colour, Combine with, Line shape, Line width, Dashed and Colour below zero.

Every history chart

• A chart can now show today, this week, this month or this year, or an earlier one, and step back and forth with buttons. Until now the period could only be "the last N hours, days, weeks or months". (#93, closes #50)

  period:
    calendar: day    # day, week, month or year
    offset: 1        # this many spans back: yesterday
    until: now       # current span: draw to now, or to its end
    navigate: true   # previous / next buttons

  • navigate: true adds ‹ and › buttons and a button named after the card's own span (Today, This week…) that returns to it. Next stops at the present. The position isn't saved to the card's config, so editing the period or reloading the dashboard returns to the configured span.
  • offset works on rolling periods too: the last 24 hours with offset: 1 is the 24 hours before those. A calendar day across a clock change is 23 or 25 hours long.
  • Days, weeks, months and years follow the time zone in your Home Assistant profile (the server's or the browser's), and weeks start on the profile's first weekday, or the language's, or Monday.
  • A span wholly in the past is loaded once: no live updates are added and statistics aren't refreshed on a timer. Stepping back to the present picks up live updates again.
  • In the editor: Chart section, Period (The last…, Today, This week, This month, This year), then Draw up to, Periods back (0 is the current one) and Show previous and next buttons.

• A chart can now combine its readings into one value per hour, day, week or month, so a line shows the daily average or each day's energy instead of every change. (#94, closes #49)

  group_by: day       # hour, day, week or month
  aggregate: change   # mean (default), sum, min, max, first, last or change

  • The average is weighted by how long each value held. History records changes, not samples, so a burst of changes doesn't outweigh a long steady stretch; Home Assistant's own statistics average the same way.
  • change adds up how much a meter rose. A drop of more than a tenth counts as a reset (counting starts again from the new reading), and smaller drops are ignored as noise. Lowest, highest, first and last include the value carried in from before the group.
  • Groups follow the calendar in your Home Assistant time zone, and the chart starts where its first group starts, so the last 7 days by day begin at midnight. A group with no readings, or one not yet begun, is a gap, never zero. The current group counts up to now.
  • With source: statistics, the card asks the recorder for only the column it needs. It asks for whole-group rows when the server's calendar matches the card's; otherwise it asks for hourly rows and groups them itself, so a browser in another time zone still gets its own days.
  • In the editor: Chart section, Group readings by, then Combine with once a grouping is chosen.

Changed

• Each entity's options now show only the fields the chosen chart reads. Any chart style used to show the line chart's colour, shape, width and dash fields, even where they did nothing. Each style now brings its own list: the line chart its line fields, the column chart a colour, and the combined chart its Draw as and Value axis fields. Bar and gauge styles are unchanged. (#95)
• Chartdeck is in the HACS default store. Search for Chartdeck in HACS and download it; there is no custom repository to add. If you added it as a custom repository before, that entry can be removed under ⋮ → Custom repositories without touching the installed card. The README badge and install steps say so too. (#100)

New in the wiki:

• Area, Column and Combined chart pages
• Calendar periods and Grouping readings on the Line page
• Installation for the HACS default store

Full changelog: v1.2.0...v1.3.0

---

Upgrading

Update via HACS, or download chartdeck-card.js from the latest release and copy it to /config/www/.

After updating, hard-refresh your browser (Ctrl/Cmd+Shift+R) so the new card module loads instead of a cached one.

---

💬 Questions or issues with this release? Reply below or open an issue.