Style Line

Line (v1.2.0+)

The first history chart. It draws how one or more sensors changed over a period, from the recorder's history or its long-term statistics. Above the chart sits a row with each entity's colour, name and current value; tapping a name opens the entity, as on the other styles. Hovering over the chart, or dragging a finger across it, shows every series' value at that moment.

Good for

Temperatures, humidity, power, prices: anything where the shape over the last hours or days matters more than the number right now.

Example

type: custom:chartdeck-card
style: line
title: Temperatures
period:
  last: 2
  unit: day
entities:
  - entity: sensor.living_room_temperature
    name: Living room
  - entity: sensor.outside_temperature
    name: Outside
    dash: true
    line_width: 4
    on_top: true

To use this style, set style: line (or pick Line under History charts in the editor's Style section). Everything below is in the editor's Chart section; the per-entity options are in each entity's options.

Period and source

period

How far back the chart looks: last (a whole number, 1 or more) and unit (hour, day, week or month). The default is the last 24 hours (the column chart's is the last 7 days). The chart keeps moving: new states are added as they arrive, without polling, and loading pauses while the card is off screen.

period:
  last: 7
  unit: day

Calendar periods (v1.3.0+)

Instead of a rolling span, a chart can show a calendar span: today, this week, this month or this year. It can also show an earlier one, and put previous and next buttons on the card.

period:
  calendar: week   # day, week, month or year
  offset: 1        # the same span this many spans ago: last week
  until: now       # current span only: draw to now (default) or to its end
  navigate: true   # previous / next buttons, and one back to the current span

• calendar is day, week, month or year. With it set, last and unit are ignored. A day runs midnight to midnight, so a day with a clock change is 23 or 25 hours long.
• offset (a whole number, 0 by default) steps back that many spans: calendar: day with offset: 1 is yesterday. It works on a rolling span too: the last 24 hours with offset: 1 is the 24 hours before those.
• until only matters for the current calendar span. now (the default) ends the chart at the present moment; end draws the whole span, leaving the part still to come empty. Earlier spans always run to their end.
• navigate: true adds ‹ and › buttons and a third button named after the card's own span (Today, This week…) to return to it. Next stops at the present. The position isn't saved to the card's config: reloading the dashboard, or editing the period, returns to the configured span.

Days, weeks, months and years follow the time zone setting in your Home Assistant profile: the server's zone when the profile says so, otherwise the browser's. Weeks start on the first weekday set in the profile, or the language's, or Monday.

A span that is wholly in the past is loaded once and stays as it is. The current span keeps moving as new states arrive.

In the editor: Chart section, Period (The last…, Today, This week, This month, This year), then either Show the last and Unit, or Draw up to; then Periods back and Show previous and next buttons.

Grouping readings (v1.3.0+)

A chart can combine its readings into one value per hour, day, week or month before drawing, so a line shows the daily average or each day's energy instead of every change.

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

• mean: the average, weighted by how long each value held. History records changes rather than regular samples, so a burst of changes doesn't outweigh a long steady stretch. Home Assistant's own statistics average the same way.
• min and max: the lowest and highest values in the group, including the one carried in from before it.
• first and last: the value at the group's start and the last one in it.
• sum: the readings taken in the group, added up.
• change: how much a meter that counts up rose during the group (energy per day, rain per hour). A drop of more than a tenth counts as a reset, and counting starts again from the new reading; smaller drops are treated as noise.

Groups follow the calendar in your Home Assistant time zone, as calendar periods do, and the chart starts where its first group starts: the last 7 days grouped by day begin at midnight. A group with no readings, or one that hasn't started yet, is left as a gap, never drawn as zero. The current group counts up to now.

With source: statistics, the card asks the recorder for the column it needs (change for sum and change, state for first and last, otherwise mean, min or max). When the server's calendar matches the card's (same time zone, weeks from Monday) it asks for rows a whole group long. 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, and Combine with once a grouping is chosen.

source

history (the default) reads the recorder's state history, every change. statistics reads the long-term statistics, which reach back further than the recorder keeps history but only exist for sensors with a state_class. The statistics period (5 minutes, hourly, daily or monthly) is picked to suit the span.

Gaps where a sensor was unavailable are left as gaps. Long histories are thinned so a wall tablet stays quick.

Lines

curve

smooth (the default, never overshooting a reading), straight or step. Set on the card for every line, or on an entity for just that one.

line_width and dots

line_width is the line's width in px, from 0.5 to 12 (2.5 by default). dots: true puts a dot at each reading. Both are set on the card and can be overridden per entity. Dots mark real readings only, and are left off a series with more than 200 readings, where they would merge into a thick line.

Per entity: color, dash and on_top

• color is a palette name or any CSS colour.
• dash: true draws the line dashed.
• on_top: true draws the line above the others where they overlap. Lines are otherwise drawn in the listed order, so the last is on top. The header and tooltip keep the listed order.

color_by

series (the default) gives each line its own colour. bands colours the line by the colour bands, so it changes colour where it crosses a threshold.

labels

labels: true prints the value at each reading. Since v2.0.0 you can choose which readings get one, where it sits, and whether labels may overlap: see Value labels.

Axes and gridlines

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

• Value labels go up the side in round steps (1, 2 or 5 times a power of ten), with a little headroom above and below the readings.
• Time labels land on round wall-clock times that suit the span: hours (with the day's name at midnight), day names for a week, day and month for longer, months with the year at January. They follow the language, 12/24-hour clock and time zone in your Home Assistant profile, and how many fit follows the card's width.
• axis_labels: outside (the default) puts the labels beside the plot; inside puts them over its edges.
• x_axis: false hides the time labels; y_axis: false hides the value labels.
• gridlines.horizontal (on by default) and gridlines.vertical (off by default) switch the lines across and down the plot.
• y_min and y_max fix either end of the value scale. A reading past a fixed end is cut off at the plot's edge. y_min must be below y_max.

Hover and touch

On by default. Moving the pointer over the chart, or dragging a finger across it, shows a guide line with a dot on each series and a box listing the time and every series' value, with the entity's own decimals and unit. An entity with no reading at that moment shows a dash. On touch, sideways drags read the chart while up and down still scrolls the page, and the box stays up for three seconds after the finger lifts.

tooltip: false turns it off (Show values on hover or touch in the editor).

Compact layout and the names row

compact: true
header: over

• compact: true cuts the card's padding, tightens the names row, shortens the plot from 180 to 110 px and uses smaller axis text.
• header places the row of names and current values: above (the default), over the chart's top-left corner on a light wash of the card's background, or hidden. Names over the chart still open their entity on tap. A hidden header leaves nothing to tap, so the entities' tap actions don't apply.

Zoom, pan and the overview strip (v2.0.0+)

zoom: true
overview: true

Option	Default	What it does
zoom	false	Lets you zoom into part of the chart and pan around it
overview	false	Adds a strip under the chart showing the whole span, with the part on show marked

With zoom: true:

• A mouse drag across the chart selects a span and zooms into it. Once zoomed, dragging pans instead.
• Two fingers pinch to zoom and move together to pan.
• Ctrl + scroll (or a trackpad pinch) zooms about the pointer, and sideways scroll pans.
• A double click or double tap goes back to the whole span, as does the Reset zoom button that appears while zoomed.
• One finger still scrubs the hover readout, and up and down still scroll the page.

Zoomed in, the chart draws only the readings in its window (and one either side), and the value axis fits them. The shortest span you can zoom to is two groups when readings are grouped, otherwise five minutes. The zoom lives on the card, not in its config: it starts again from the whole span when you step to another period or reload the dashboard.

overview: true draws a strip under the chart with every series' line over the whole span and a window marking the part on show. Drag the window to move it, drag its edges to resize it, or drag across the strip to choose a new one. Tap the strip to centre the window there, and double-tap to show everything again. With the strip focused, the arrow keys move the window, up and down (or + and −) zoom, and Escape resets. The strip works with or without zoom.

Zoom and the overview strip are on the line chart only, and are not drawn when the card shows small multiples.

In the editor: Chart section, Zoom and pan (pinch, Ctrl + scroll or drag) and Overview strip below the chart.

Annotations (v2.0.0+)

Annotations mark things on the chart that aren't readings: a target, a comfort range, a time of day, when something switched on, or a label on a reading.

annotations:
  - type: line
    value: 21
    label: Target
  - type: band
    from: 18
    to: 20
    label: Comfort
    color: green
  - type: time
    times: "07:00"
    label: Wake
  - type: state
    entity: binary_sensor.window
    state: "on"
    shade: true
    label: Window open
  - type: point
    at: max
    label: Peak
zones: true

type	Options	What it draws
line	value (needed), dash (default true)	A line across the chart at a value
band	from, to (one is needed)	A shaded band between two values; leave one out to run to the chart's edge
time	times	A line down the chart at each time: "07:00" every day, or "2026-10-28 07:00" once; a list, or text with commas
state	entity (needed), state, shade	A mark each time the entity changes (or changes to state); shade: true also shades the stretches while it is in that state
point	at (max, min, last or first), entity	A label on that reading of a series (the first series unless entity names another)

Every annotation also takes label and color (a palette name or any CSS colour). Default colours are red for lines, green for bands, grey for times, amber for states and the primary colour for points. value, from and to can be a number or an entity id whose state is the number, so a threshold can follow an input_number.

• Threshold lines widen the value axis, so a target outside the readings' range still shows.
• Labels for time and state marks run along the top of the plot in two rows. Above 60 marks from one annotation, only the lines are drawn, since the labels would smear together.
• zones: true shades the first entity's colour bands faintly behind the chart, as severity zones.
• A mistake in an annotation (a missing value on a line, a time the card can't read) is reported on the card with the entry's position, such as "annotations[2].times" has "7am": use 07:00 or 2026-10-28 07:00.

Annotations are on the line chart only, and are not drawn when the card shows small multiples.

In the editor: Chart section, Shade the severity bands behind the chart for zones, then the Annotations list under it. Add an annotation: has a button for each kind, and each entry has its own fields.

Value labels (v2.0.0+)

labels: true
labels_show: minmax
labels_position: auto
labels_overlap: false

Option	Default	What it does
labels	false	Prints values on the readings
labels_show	all	Which readings: all (as many as fit), last (the latest), minmax (highest and lowest) or ends (first and latest)
labels_position	auto	Where each label sits: auto (above peaks, below dips), above, below or center (on the point)
labels_overlap	false	Lets labels overlap instead of leaving out the ones that would collide

Labels are placed most important first: the latest reading, then the highest and lowest, then the rest in time order. Each takes the first of its sides that is clear of the labels already placed and stays inside the plot. A label with no clear side is left out, unless labels_overlap: true. With overlap allowed and labels_show: all, a series with more than 40 readings gets no labels at all. Gaps are never labelled, and neither are the values carried in at the left edge or on to the right edge, which are not new readings. Labels near the plot's left or right edge line up with it instead of running off.

Labels use each entity's own decimals. They follow the zoom window, and each small multiple gets its own.

In the editor: Chart section, Show values on the points, then Which readings, Label position and Let labels overlap once it is on.

Synced charts (v2.0.0+)

sync: house

Line charts with the same sync group name share what the pointer is over. Hovering or touching one shows the guide line and the hover box at the same moment on every other chart in the group. They also share previous and next steps: stepping back a day on one steps back every chart in the group that covers the same kind of period and has its own buttons. Cards find each other anywhere on the dashboard, in stacks, grids or other columns.

A chart doesn't show another chart's moment while your own pointer is on it. In small multiples, every small chart's title shows its reading at the shared moment. Zoom is not shared between charts.

In the editor: Chart section, Sync group (charts with the same name share the pointer and period steps).

Small multiples (v2.0.0+)

multiples: true
multiples_scale: auto
multiples_columns: 3

Option	Default	What it does
multiples	false	Draws one small chart per entity in a grid, instead of every line in one chart
multiples_scale	auto	auto: one value scale when every entity reads in the same unit, a scale each when they don't. shared: one for every chart. independent: each chart its own
multiples_columns	fits the card	How many charts go across, 1 to 6. Left empty, as many fit as are at least 150 px wide

The small charts share the time axis. Each has the entity's name and current value as its title, which opens the entity like the header does. While the pointer is over any of them, every title shows its reading at that moment. An entity with no readings in the span says so in its own place. The period buttons stay above the grid.

In small-multiples mode each chart draws its line, value labels and hover readout. Zoom, the overview strip, annotations and highest/lowest marks are not drawn.

In the editor: Chart section, A small chart for each entity, then Value scale and Columns (empty fits the card) once it is on.

Highest, lowest and average (v2.0.0+)

extremes:
  max: true
  min: true
  average: line
entities:
  - entity: sensor.living_room
  - entity: sensor.outside
    extremes: false

Option	Default	What it does
extremes.max	false	A ringed dot and a label ("High 14.2 °C · 14:10") at each series' highest reading
extremes.min	false	The same at the lowest reading
extremes.average	none	line: a dashed line across at the average, labelled at the right edge. figure: the label only. none: nothing
Per entity extremes	true	false leaves that series out of the marks

• Only readings taken in the period count. Gaps don't, and nor does the value carried in from before the start.
• The average on raw history is weighted by how long each value held, so a room at 20 °C all night that flickered to 25 °C for a minute averages near 20. It stops at now, and unavailable stretches count for nothing. Grouped or statistics readings get a plain mean, as each is one equal period.
• The times in the labels follow your language, clock and time zone. A grouped reading names its group (the day, or the month).
• Labels keep clear of the dots, of each other and of a header laid over the chart. When neither side is clear they take a side that fits.
• Marks follow the zoom window. They are not drawn in small multiples.

In the editor: Chart section, Mark the highest reading, Mark the lowest reading and Average. While any mark is on, each entity's options gain a Mark highest, lowest and average switch to leave it out.

Logarithmic value scale (v2.0.0+)

y_scale: log

y_scale: log puts the value axis on powers of ten, for readings that span several orders of magnitude, such as light from a dim room to full sun, or network traffic with spikes. linear (the default) keeps even steps.

• Labels go at each power of ten. Within a decade or two they go at 1, 2 and 5. Across many decades every second or third power is labelled, and the steps between are drawn as fainter gridlines. Small ticks get the decimals they need (0.01) and large ones read short (10K, 1M).
• Zero and negative readings have no place on a log axis, so they are left as gaps in the line, and the axis starts from the smallest reading above zero. The hover readout still shows their real value.
• A chart with nothing above zero says Nothing above zero to draw on a log scale. instead of drawing an empty axis.
• y_min and y_max must be above 0 with a log scale; the card says so if they aren't.
• Colouring by bands (color_by: bands) places its colour changes through the scale, so the line changes colour where the value is drawn.

The log scale is on the line chart only. Columns, areas and the other history charts stand on zero, so they always draw on even steps, whatever y_scale says.

In the editor: Chart section, Value scale (Even steps or Logarithmic (powers of ten)).

Layout: one chart for the whole card. Every shared option is described on the Options page.

Previous: Arc · Next: Area · All styles