Sparkline history periods and bins¶

The period defines the time range shown by a sparkline. Bins divide that range into equal intervals and determine how much detail the graph preserves. The aggregate function then chooses whether each interval displays its average, minimum, maximum, or another supported value.

Set period.type to the range you want to display, then configure the corresponding settings block.

Period types¶

Realtime¶

Realtime mode displays only the latest value and does not include a timeline. Use it with chart types that can represent a single live state.

1
2

period:
  type: real_time

Choose realtime when only the current state matters. Use rolling_window or calendar for charts that need to show a trend over time.

Rolling window¶

A rolling window always covers the most recent configured duration. Its bins align with the selected interval, and the final bin represents the current active interval.

1
2
3
4
5
6
7
8

period:
  type: rolling_window
  rolling_window:
    duration:
      hour: 24
    bins:
      per_hour: auto
      density: medium

This example automatically chooses a suitable interval for the latest 24 hours. As time moves forward, older bins leave the range and a new current bin is added.

Calendar range¶

Calendar mode follows calendar boundaries, such as local midnight at the start of a day.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

period:
  type: calendar
  calendar:
    period: day
    offset: 0
    duration:
      hour: 24
    bins:
      per_hour: auto
      density: medium

For the current day, the X-axis spans the full 24-hour period. Values continue to appear up to the current interval as the day progresses.

Use a negative offset to display a completed calendar period:

1
2
3
4
5
6
7
8
9

period:
  type: calendar
  calendar:
    period: day
    offset: -1
    duration:
      hour: 24
    bins:
      per_hour: 2

A completed calendar period remains unchanged throughout the day. When the local date changes, the same offset points to the next corresponding historical period.

Duration¶

Duration determines how much time the graph covers. Hours work well for compact daily and multi-day history graphs.

Changing the graph’s width or height does not affect the selected time range. In automatic mode, the configured width helps FHS choose how many bins fit comfortably. A manually configured bins.per_hour remains unchanged when the graph size changes.

Bins per hour¶

By default, FHS chooses bins.per_hour automatically from the duration, configured graph width, chart type, and selected density:

1
2
3

bins:
  per_hour: auto
  density: medium

Use low for a calmer graph with fewer bins, medium for the normal balance, or high to retain more detail. Line and area charts can display more detail than charts that draw every bin as a separate shape. Radial barcodes use the available circumference of the graph.

Automatic mode selects one of these intervals:

Set per_hour to a number when you need an exact interval:

1
2

bins:
  per_hour: 30

A numeric value always takes precedence over density, so this example keeps two-minute bins at every duration and width. Using more bins preserves shorter peaks and dips, but also creates a denser graph. Using fewer bins produces a calmer view because more measurements are combined into each displayed value.

State bands and bins¶

The state_bands chart uses the actual times at which the entity changed state. Its segments are therefore independent of the configured number of bins.

state_bands.update_interval determines how often the end of an unchanged current state advances toward the current time.

Aggregation¶

Configure aggregation and value handling under state_values.

1
2
3
4
5

sparkline:
  state_values:
    aggregate_func: avg
    smoothing: true
    logarithmic: false

The tooltip and derived FHS entities use the minimum, average, and maximum values from the selected time interval.

Empty and active bins¶

A time interval without measurements has no minimum, average, or maximum tooltip values, even when the line itself appears continuous.

Rolling-window graphs and current calendar graphs update automatically when Home Assistant provides a new state. The graph, tooltip, and minimum, average, and maximum values then reflect the updated current interval.

Time zones and boundaries¶

Dates and times follow the local Home Assistant or browser time zone. Midnight therefore marks the transition to the next local day.

A rolling window follows a continuously moving time range. A calendar graph follows the selected local calendar period. For the current day, the X-axis already spans the full day, even though later intervals do not yet contain data.

When history updates¶

When the card opens, the graph loads the selected period. Current periods continue to update as Home Assistant provides new states and advance whenever a new time interval begins.

A completed calendar period remains unchanged during the day. At the next local day transition, an offset such as -1 points to a different date, and the graph updates to show that period.

Returning to a view after it has been inactive also refreshes the graph when the requested period has changed.

Related documentation¶

• Sparkline Graphs
• Sparkline Cartesian Charts and Axes
• Sparkline Specialized Charts