Waterfall History Card for Home Assistant

v4.2 - Historical Time Window Offset

What's New in v4.2

New: start_offset option - View historical time windows (e.g., yesterday's data)
Compare today vs yesterday by showing same entity with different offsets
Configurable globally or per-entity

What does this card do?

Horizontal waterfall charts - visualize entity history as a sequence of colored bar segments.
Customizable time window - choose how many hours to show and how many intervals to split into.
Threshold-based colors - colors automatically adapt to value thresholds (configurable).
Binary sensor customization - customize on/off colors and state labels for binary sensors, switches, and other binary entities.
Binary state labels - display "On"/"Off", "Open"/"Closed", "Unlocked"/"Locked" instead of numeric values.
Unknown/unavailable state handling - entities in unknown or unavailable states display with customizable colors and labels instead of errors.
Entity icons - show icons next to entity names; toggle globally or per-entity.
Compact mode - shrink fonts and spacing for tighter dashboards.
Inline layout mode - display entity name, graph, and current value on a single line.
Short duration event detection - captures brief state changes for binary entities (doors, motion, lights).
Per-entity overrides - customize hours, intervals, labels, icons, colors, state labels, and display options per entity.

Installation

Quick Start

Basic Configuration

type: custom:waterfall-history-card
title: Room Temperatures
entities:
  - entity: sensor.outdoor_temperature
    name: Outside
  - entity: sensor.indoor_temperature
    name: Inside

Binary Sensors with State Labels

type: custom:waterfall-history-card
title: Doors & Windows
state_on: "Open"
state_off: "Closed"
color_on: '#FFC107'
color_off: '#4CAF50'
entities:
  - binary_sensor.front_door
  - binary_sensor.back_door
  - binary_sensor.garage_door

Configuration

Card-Level Options

Option	Type	Default	Description
`title`	`string`	`"History"`	Card title shown at the top.
`entities`	`array`	required	List of entity objects to display (see per-entity options below).
`hours`	`number`	`24`	Time range in hours to show history.
`intervals`	`number`	`48`	Number of intervals (bars) to divide the history into.
`start_offset`	`number`	`0`	Hours to offset the time window (e.g., 24 = show 24-48h ago instead of 0-24h).
`height`	`number`	`60`	Height in pixels of each entity's waterfall chart.
`show_labels`	`boolean`	`true`	Show the "X hours ago" / "now" labels under the bar.
`show_min_max`	`boolean`	`false`	Show min/max values under the chart.
`show_current`	`boolean`	`true`	Show the current value next to the entity name.
`show_icons`	`boolean`	`true`	Show entity icons globally. Can be overridden per entity.
`compact`	`boolean`	`false`	Use smaller font sizes and spacing.
`inline_layout`	`boolean`	`false`	Display name, graph, and value on a single line.
`color_on`	`string`	`#EEEEEE`	Color for binary sensors in "on" state (global default).
`color_off`	`string`	`#636363`	Color for binary sensors in "off" state (global default).
`binary_colors`	`object`	-	Alternative way to set binary colors: `{on: '#color', off: '#color'}`.
`state_on`	`string`	`"On"`	Matches the HA state string for "on" and sets the display label (global default). E.g. `"home"` for a person entity.
`state_off`	`string`	`"Off"`	Matches the HA state string for "off" and sets the display label (global default). E.g. `"not_home"` for a person entity.
`color_unknown`	`string`	`#FF9800`	Color for entities in "unknown" state (orange).
`color_unavailable`	`string`	`#9E9E9E`	Color for entities in "unavailable" state (gray).
`state_unknown`	`string`	`"Unknown"`	Label to display for entities in "unknown" state.
`state_unavailable`	`string`	`"INOP"`	Label to display for entities in "unavailable" state.
`thresholds`	`array`	see below	Color thresholds for numeric sensors.
`interval_value`	`string`	`"last"`	How to represent each bucket: `last` (final value), `min` (lowest value), `max` (highest value).
`gradient`	`boolean`	`false`	Use gradient interpolation between thresholds.
`digits`	`number`	`1`	Number of decimal places for numeric values.
`unit`	`string`	auto	Override unit of measurement.
`card_mod`	`object`	-	card-mod configuration for advanced styling.

Per-Entity Options

Each item in entities: can be either a bare entity ID string, or an object with these fields:

Option	Type	Default	Description
`entity`	`string`	required	The entity ID (e.g., `sensor.living_room_temp`).
`binary_colors`	`object`	Inherits from card	Alternative: `{on: '#color', off: '#color'}` for this entity.
`color_off`	`string`	Inherits from card	Color for this binary entity's "off" state.
`color_on`	`string`	Inherits from card	Color for this binary entity's "on" state.
`color_unavailable`	`string`	Inherits from card	Color for this entity when in "unavailable" state.
`color_unknown`	`string`	Inherits from card	Color for this entity when in "unknown" state.
`digits`	`number`	Inherits from card	Override decimal places for this entity.
`hours`	`number`	Inherits from card	Override the number of hours shown for this entity.
`inline_layout`	`boolean`	Inherits from card	Use inline layout for this entity.
`interval_value`	`string`	Inherits from card	How to represent each bucket: `last`, `min`, or `max`.
`intervals`	`number`	Inherits from card	Override the number of intervals (bars) for this entity.
`name`	`string`	Friendly name / ID	Override the display name.
`show_current`	`boolean`	Inherits from card	Show/hide current value just for this entity.
`show_icons`	`boolean`	Inherits from card	Show/hide the icon for just this entity (overrides global setting).
`show_labels`	`boolean`	Inherits from card	Show/hide labels just for this entity.
`show_min_max`	`boolean`	Inherits from card	Show/hide min/max just for this entity.
`start_offset`	`number`	Inherits from card	Hours to offset the time window for this entity.
`state_off`	`string`	Inherits from card	Matches the HA state string for "off" and sets the display label for this entity.
`state_on`	`string`	Inherits from card	Matches the HA state string for "on" and sets the display label for this entity.
`state_unavailable`	`string`	Inherits from card	Label to display when this entity is "unavailable".
`state_unknown`	`string`	Inherits from card	Label to display when this entity is "unknown".
`thresholds`	`array`	Inherits from card	Override color thresholds for this entity.
`unit`	`string`	Inherits from card	Override unit of measurement for this entity.

How Each Interval Is Represented: `interval_value`

The time range is divided into equal-width buckets (controlled by intervals). Multiple state changes can occur within a single bucket. The interval_value option controls which value is used to represent each bucket.

Value	Behavior	Use case
`last`	Last recorded state in the bucket (default)	General use; shows where the entity ended up
`min`	Lowest value recorded in the bucket	Detecting brief dips (e.g., latency spike to 0)
`max`	Highest value recorded in the bucket	Detecting brief activations (e.g., door briefly opened)

For binary sensors, on=1 and off=0, so:

interval_value: max - shows the bucket as "on" if the entity was on at any point, even briefly
interval_value: min - shows the bucket as "off" if the entity was off at any point, even briefly
interval_value: last (default) - shows whichever state the entity was in at the end of the bucket; brief events that return to the original state are not visible

For numeric sensors, min and max capture the extreme value within the bucket rather than just the final reading.

Examples (binary sensor, 1-minute buckets):

Activity in bucket	`last`	`min`	`max`
Closed → Open → Closed	Off	Off	On
Open → Closed → Open	On	Off	On
Closed the whole time	Off	Off	Off

Set globally or per-entity:

# Detect any brief door opening within each bucket
- entity: binary_sensor.front_door
  interval_value: max
  state_on: "Open"
  state_off: "Closed"

# Detect any brief latency drop to zero
- entity: sensor.wan_latency
  interval_value: min

Examples

Basic Multi-Entity Temperature Card

type: custom:waterfall-history-card
title: Room Temperatures
hours: 12
intervals: 24
entities:
  - entity: sensor.living_room_temp
    name: Living Room
    show_icons: false
  - entity: sensor.kitchen_temp
    hours: 6

Historical Comparison with Start Offset

Compare today's data with yesterday's data by using start_offset:

type: custom:waterfall-history-card
title: Temperature Comparison
hours: 24
entities:
  # Today's temperature (default, no offset)
  - entity: sensor.outdoor_temperature
    name: Today
  # Yesterday's temperature (24 hour offset)
  - entity: sensor.outdoor_temperature
    name: Yesterday
    start_offset: 24

The start_offset shifts the time window back by the specified hours. With hours: 24 and start_offset: 24, you see data from 24-48 hours ago instead of 0-24 hours ago.

Using CardMod to adjust spacing

You can use card-mod to adjust the amount of space given for the entity name and graph 'columns'. Use this to adjust as necessary to avoid truncated entity names and give as much space as desired for the graph element.

type: custom:waterfall-history-card
title: Temperature History
inline_layout: true
entities:
  - sensor.outdoor_temperature
  - sensor.indoor_temperature
card_mod:
  style: |
    .entity-inline-container .entity-inline-name {
      width: 120px !important;
    }
    .entity-inline-container .entity-inline-value {
      width: 60px !important;
    }

Binary Sensors with Custom State Labels

type: custom:waterfall-history-card
title: Home Security
# Global state labels
state_on: "Alert"
state_off: "Normal"
entities:
  # Uses global labels ("Alert" / "Normal")
  - binary_sensor.motion_living_room

  # Custom labels for door
  - entity: binary_sensor.front_door
    name: Front Door
    state_on: "Open"
    state_off: "Closed"
    color_on: '#FFC107'
    color_off: '#4CAF50'

  # Custom labels for lock
  - entity: lock.front_door
    name: Door Lock
    state_on: "Unlocked"
    state_off: "Locked"
    color_on: '#FF5722'
    color_off: '#4CAF50'

Binary State Label Customization

Global State Labels

Set default labels for all binary entities:

type: custom:waterfall-history-card
title: Home Status
state_on: "Active"
state_off: "Inactive"
entities:
  - binary_sensor.motion_living_room
  - switch.kitchen_light

Per-Entity State Labels

Override labels for specific entities:

type: custom:waterfall-history-card
title: Security
entities:
  - entity: binary_sensor.front_door
    state_on: "Open"
    state_off: "Closed"
  - entity: lock.front_door
    state_on: "Unlocked"
    state_off: "Locked"

Custom State Matching for Non-Binary Entities

Entities like person or device_tracker use state strings other than on/off. Use state_on and state_off to tell the card which HA state values map to on/off. The same values are used as the display labels.

type: custom:waterfall-history-card
title: Presence History
hours: 12
entities:
  - entity: person.jane
    state_on: "home"
    state_off: "not_home"
    color_on: "#4CAF50"
    color_off: "#9E9E9E"

Note: check the exact state values your entity uses in Developer Tools -> States. For example, person.* uses home and not_home; device_tracker.* may use home and not_home or zone names.

Supported Binary Entity Types

state_on/state_off work with any entity type, including:

binary_sensor.* (motion, door, window, etc.)
switch.*
light.* (on/off only)
input_boolean.*
person.* (e.g. home / not_home)
device_tracker.*
alarm_control_panel.*
cover.* (e.g. open / closed)

Color Precedence

When multiple color configurations exist, the card uses this priority:

Per-entity binary_colors or color_on/color_off
Global binary_colors or color_on/color_off
Default colors (#636363 off, #EEEEEE on)

Supported Color Formats

All standard CSS color formats are supported:

Hex: #FF0000 or #F00
RGB: rgb(255, 0, 0)
RGBA: rgba(255, 0, 0, 0.5)
Named: red, blue, green, etc.
HSL: hsl(0, 100%, 50%)

Default Thresholds (Numeric Sensors)

For numeric sensors (like temperature), the card uses these default thresholds if none are specified:

thresholds:
  - value: 60
    color: "#4FC3F7"
  - value: 70
    color: "#81C784"
  - value: 80
    color: "#FFB74D"
  - value: 100
    color: "#FF8A65"

Threshold	Color	Description
60	`#4FC3F7`	Cold (blue)
70	`#81C784`	Cool (green)
80	`#FFB74D`	Warm (orange)
100	`#FF8A65`	Hot (red)

Default Colors (Binary Sensors)

For binary sensors (on/off), the card uses these default colors and labels if none are specified:

State	Color	Label	Description
Off/0	`#636363`	"Off"	Dark gray
On/1	`#EEEEEE`	"On"	Light gray

These can be overridden globally or per-entity using color_on/color_off and state_on/state_off.

Default Colors (Unknown & Unavailable States)

For entities in unknown or unavailable states, v3.2 uses these default colors and labels:

State	Color	Label	Description
Unknown	`#FF9800`	"Unknown"	Orange
Unavailable	`#9E9E9E`	"INOP"	Gray

These can be overridden globally or per-entity using color_unknown/color_unavailable and state_unknown/state_unavailable.

US National Weather Service Temperature Color Scale

type: custom:waterfall-history-card
title: NWS Color Temp Sensors
thresholds:
  - value: 0
    color: "#9370DB"
  - value: 10
    color: "#4169E1"
  - value: 20
    color: "#00BFFF"
  - value: 30
    color: "#00FFFF"
  - value: 40
    color: "#32CD32"
  - value: 50
    color: "#ADFF2F"
  - value: 60
    color: "#FFD700"
  - value: 70
    color: "#FFA500"
  - value: 80
    color: "#FF4500"
  - value: 90
    color: "#FF0000"
  - value: 100
    color: "#8B0000"
  - value: 110
    color: "#800000"
entities:
  - entity: sensor.outside_temp

Contributing

Issues and pull requests welcome on GitHub!

License

MIT License - see LICENSE file for details

Name		Name	Last commit message	Last commit date
Latest commit History 143 Commits
.github		.github
dist		dist
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
hacs.json		hacs.json
horizontal-waterfall-history-card.js		horizontal-waterfall-history-card.js
package-lock.json		package-lock.json
package.json		package.json
rollup.config.js		rollup.config.js
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Waterfall History Card for Home Assistant

v4.2 - Historical Time Window Offset

What's New in v4.2

What does this card do?

Installation

Quick Start

Basic Configuration

Binary Sensors with State Labels

Configuration

Card-Level Options

Per-Entity Options

How Each Interval Is Represented: interval_value

Examples

Basic Multi-Entity Temperature Card

Historical Comparison with Start Offset

Using CardMod to adjust spacing

Binary Sensors with Custom State Labels

Binary State Label Customization

Global State Labels

Per-Entity State Labels

Custom State Matching for Non-Binary Entities

Supported Binary Entity Types

Color Precedence

Supported Color Formats

Default Thresholds (Numeric Sensors)

Default Colors (Binary Sensors)

Default Colors (Unknown & Unavailable States)

US National Weather Service Temperature Color Scale

Contributing

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 26

Uh oh!

Contributors

Uh oh!

Languages

How Each Interval Is Represented: `interval_value`