🚀 Release: v1.2.0

[github-actions[bot]]

🚀 New Release: v1.2.0

View full release and download on GitHub

---

The first history chart. style: line draws how one or more sensors changed over the last hours, days, weeks or months, from the recorder's history or its long-term statistics, and keeps itself up to date as new states arrive. It comes with value and time labels and gridlines, a hover and touch readout, per-line widths, dots and stacking order, and a compact layout for tight dashboards. Everything is settable from the visual editor's new Chart section. Nothing about your existing cards needs changing: the bar and gauge styles draw exactly as before.

Added

Line chart

• A card can now show a sensor's history as a line chart. Set style: line (or pick Line under History charts in the Style section) and the card draws every listed entity as a line over the chosen period, with a row above the chart giving each entity's colour, name and current value. Tapping a name opens the entity, and hold and double-tap actions work as on the other styles. (#86, closes #9)

  type: custom:chartdeck-card
  style: line
  title: Temperatures
  period:
    last: 2
    unit: day
  source: history
  curve: smooth
  entities:
    - entity: sensor.living_room_temperature
      name: Living room
    - entity: sensor.outside_temperature
      name: Outside
      color: orange
      dash: true

  • period sets how far back it looks: last is a whole number and unit is hour, day, week or month. The default is the last 24 hours.
  • source: history (the default) reads every state change from the recorder. source: statistics reads long-term statistics instead, which reach back much further but only exist for sensors with a state_class; the card picks 5-minute, hourly, daily or monthly statistics to suit the span.
  • New states are added to the chart as they arrive over the existing connection, with no polling. When the card leaves the screen or the connection drops, loading pauses and picks up again when it comes back.
  • curve is smooth (which never overshoots a reading), straight or step, for the whole card or per entity. Each entity can have its own color (a palette name or any CSS colour) and can be drawn dashed.
  • color_by: bands colours the line by the card's colour bands, so it changes colour where it crosses a threshold. labels: true prints the value at each point, and is skipped on a series with more than 40 points where the labels would overlap.
  • Times when a sensor was unavailable are left as gaps rather than joined across. Long histories are thinned before drawing so a wall tablet stays quick.
  • While history is loading, if it fails, or if there are no readings in the period, the card says so in place of the chart.

Axes and gridlines

• Line charts have value labels up the side, time labels along the bottom and light gridlines across the plot, so a reading can be checked without hovering. (#87, closes #48)

  axis_labels: outside
  gridlines:
    horizontal: true
    vertical: true
  y_min: 0
  y_max: 30

  • Value labels use round steps (1, 2 or 5 times a power of ten), and the range fits the readings with a little headroom, rounded out to the next step. y_min and y_max fix either end exactly; a reading beyond a fixed end is cut off at the plot's edge, and a y_min that isn't below y_max is reported as a config error.
  • Time labels land on round wall-clock times that suit the span: every few minutes or hours (with the day's name at midnight), day names across a week, day and month for longer, then months (with the year at January) and years. They follow the language, 12/24-hour clock and time zone set in your Home Assistant profile, and stay on local midnight across clock changes.
  • How many time labels fit follows the card's width, and is re-worked when the card is resized.
  • axis_labels: outside (the default) puts the labels beside the plot; inside lays them over the plot's edges to give the lines the full width. x_axis: false or y_axis: false hides either set.
  • gridlines.horizontal is on by default and gridlines.vertical off. The lines and labels take the theme's divider and secondary text colours, so they suit light and dark themes.
  • All of it is in the editor's Chart section.

Hover and touch readout

• Moving the pointer over a line chart, or dragging a finger across it, shows every series' value at that moment. A vertical guide follows the pointer with a dot on each line, and a box lists the time and each entity's value with its own decimals and unit. (#88, closes #39)

  tooltip: true

  • The guide snaps to the nearest reading in time across all the series. An entity with no reading at that moment (unavailable, or in a gap) shows a dash and gets no dot.
  • The box sits to the right of the guide when there is room and to the left when there isn't, and is pinned to the plot's edge on cards too narrow for either.
  • On a phone, sideways drags read the chart while up-and-down still scrolls the page, and the box stays up for three seconds after your finger lifts so it can be read. With a mouse it hides as soon as the pointer leaves the plot.
  • Tapping, holding or double-tapping a name in the row above the chart still runs its action; the readout only listens on the plot.
  • It's on by default. Show values on hover or touch in the Chart section (tooltip: false) turns it off.

Line widths, dots and drawing order

• Each line can have its own width, a dot at each reading, and be drawn above the others, so a thick outside temperature can stay on top of thin room lines where they cross. (#89, closes #51)

  line_width: 1.5
  dots: false
  entities:
    - entity: sensor.bedroom_temperature
    - entity: sensor.kitchen_temperature
    - entity: sensor.outside_temperature
      line_width: 4
      dots: true
      on_top: true

  • line_width (0.5 to 12 px, 2.5 by default) and dots are set on the card and can be overridden per entity.
  • Lines are drawn in the listed order, so the last is on top; any marked on_top are drawn after those. The names row and the hover readout keep the listed order either way.
  • Dots mark real readings only, not the value carried to the chart's edge, and take the line's colour (or the band colour with color_by: bands). They are left off a series with more than 200 readings, where they would merge into a thick line.
  • In the editor the card-wide width and dots are in the Chart section. Each entity's width, dots and Draw above the other lines sit with its colour, shape and dash options. An entity's dots switch shows the card's setting until you change it, and switching it back removes the override.

Compact layout

• A line chart can be drawn tighter for dashboards where space is short, with its names row moved over the chart or hidden. (#90, closes #52)

  compact: true
  header: over

  • compact: true cuts the padding round the card, tightens the names and values row, shortens the plot from 180 to 110 px and uses smaller axis text.
  • header places the names and current values: above the chart (the default), over the chart's top-left corner on a light wash of the card's background with the value a little larger, or hidden.
  • Names drawn over the chart still open their entity on tap, and pressing them doesn't also move the hover readout. While the chart is loading or has no readings, the names go above the message instead. With axis_labels: inside, the top value label is hidden so it doesn't sit under the names.
  • A hidden header leaves nothing to tap, so the entities' tap, hold and double-tap actions have nothing to attach to.
  • Both are in the Chart section, as Names and values and Compact.

Changed

• The style picker is grouped by kind. Bars, gauges and history charts now sit under their own headings in the editor's Style section, ready for the charts still to come. Under the hood a style can now draw the whole card as one chart, with its own option checks, editor section and thumbnail. The seven bar and gauge styles are unchanged. (#85)

Upgrading

Nothing to do: existing cards keep working exactly as they did. Update through HACS and reload your browser, then pick Line in the Style section of any card, or add style: line to its YAML.

Every line chart option is on the new wiki page Line, with sections on period and source, lines, axes and gridlines, hover and touch and the compact layout. source: statistics needs the sensor to have a state_class; without one, use the default source: history.

Full changelog: v1.1.0...v1.2.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.