Utility Meter Card

Features

• Two cards: a full Utility Meter Card (custom:utility-meter-card) and a compact Utility Meter Mini Card (custom:utility-meter-mini-card)
• Water and gas meters, the kind of meter read from the sensor's device class (or forced with meter_type)
• Index of the meter, in its unit, with the meter's usual digits (three decimals for m³)
• Consumption of today, this week, this month and this year, from the long-term statistics, or live from a utility_meter helper fed by the meter when there is one
• Comparison with the previous period at the same point: today until now against yesterday until the same hour, this month so far against the same time elapsed last month… as a percentage, orange when it goes up, green when it goes down
• History chart of the day (hours), the week (days), the month (days) or the year (months), each bar in front of the same slot of the previous period, with the average; a click on a bar opens its details (consumption, cost, previous period) in a popup at the top of the card
• Cost (optional): a fixed price or a price entity, per m³ or per kWh — with a conversion factor for gas meters counting m³ — in Home Assistant's currency or your own
• Leak detection: water used every single hour of a night window (01:00 – 05:00 by default) above a threshold (2 L/h by default) raises an alert; a leak sensor (binary_sensor) and a daily limit can raise one too. The status pill turns red (orange for the daily limit), an alert banner appears and the night section unfolds
• Drawn water meter and gas meter, animated by their state (see Animations): water flowing, gas burning, leak
• Live flow from a flow sensor (flow_entity), which also drives the animation
• Header icon of the kind of meter in a tinted round badge, colored with the meter state, and a status pill on the title line
• Collapsible sections (the night section folded by default, unfolded on a suspected leak); a click anywhere else folds them back
• Sections view: the full card takes 12 columns by default and at least 6, the mini card 6; narrow widths get their own layout (see Screenshots)
• Detail button on the mini card (top right): it switches the mini card to the full card's content and back; a click anywhere outside the card brings the compact view back
• Click any value to open its Home Assistant history (more-info dialog)
• Visual editor in the dashboard UI for both cards (no YAML needed)
• Light and dark mode, English, French, German, Spanish, Serbian (Cyrillic and Latin), Italian, Dutch, European Portuguese, Polish, Romanian, Danish, Swedish, Bulgarian, Russian, Ukrainian, Hungarian, Slovak, Czech, Slovenian, Latvian and Greek
• Single file, no external dependency; each language other than English is a small file loaded on demand

Supported integrations

The cards read a cumulative sensor (state_class: total or total_increasing) with the water or gas device class, and its long-term statistics. Anything that provides one works, for example:

Source	Kind	What the cards use
Pulse counters — ESPHome pulse_meter / pulse_counter with a total, Shelly, Zigbee or Z-Wave pulse readers	Water, gas	The index sensor and its statistics; the flow sensor as flow_entity
AI-on-the-edge-device (camera reading a meter)	Water, gas	The index sensor and its statistics
Gazpar / GRDF custom integrations, such as home-assistant-gazpar	Gas	The gas sensor the integration exposes (m³ or kWh), or statistic_id for the statistics it imports; price_unit: energy with the conversion factor of your bill for a price per kWh
Suez Water (core) and the custom integrations of other water companies (Veolia, Eau de Paris…)	Water	The water sensor; statistic_id for the statistics the integration imports (its daily data is a day late, so the Day tab is left out when there is no hourly data)
Utility Meter helpers (core)	Water, gas	Daily, weekly, monthly and yearly helpers fed by the meter are found on their own and give the live value of their period (and their previous period when there are no statistics); today_entity, week_entity, month_entity, year_entity pick others
Any binary_sensor leak / moisture sensor	Water	leak_entity: raises the leak alert when it turns on

The statistics are the ones Home Assistant keeps for every sensor with a state class (the same as the Energy dashboard's water and gas sources).

Prerequisites

Home Assistant 2024.8 or later, the recorder (on by default) and a water or gas meter sensor.

Configuration

Card types#

Visual editor#

Edit a dashboard, click Add card and search for Utility Meter Card or Utility Meter Mini Card. The first water meter is preselected (then the gas meters); pick another one in the list, set an optional title, the default chart, the sections to display, the cost, the leak detection and the data sources. The preview updates live, and options left at their default are kept out of the generated YAML.

Minimal#

type: custom:utility-meter-card
entity: sensor.water_meter

type: custom:utility-meter-mini-card
entity: sensor.gas_meter

Full options#

type: custom:utility-meter-card
entity: sensor.water_meter
title: House water
meter_type: auto
chart_period: week
show_picture: true
show_index: true
show_consumption: true
show_comparison: true
show_chart: true
show_cost: true
liters: true
collapsed: [night]
# Cost
price_entity: sensor.water_price   # or price: 4.34
currency: EUR
price_unit: volume
# Leak detection
leak_detection: true
leak_start: "01:00"
leak_end: "05:00"
leak_threshold: 2
daily_limit: 0.5
flow_entity: sensor.water_flow
leak_entity: binary_sensor.utility_room_leak
# Data sources
statistic_id: sensor.water_meter
today_entity: sensor.water_daily

A gas meter counting m³ with a price per kWh (Gazpar):

type: custom:utility-meter-card
entity: sensor.gazpar_index
price: 0.105
price_unit: energy
conversion_factor: 11.2
chart_period: year

Options reference#

How it works

Statistics#

The card asks Home Assistant for the long-term statistics of the meter (recorder/statistics_during_period, the change of each period): hourly from two days back (today, yesterday and last night) and daily from the 1st of January of last year (the weeks, months and years and the previous ones). The statistics come in the sensor's unit (an imported statistic kept in another unit of the same kind is converted by Home Assistant). Home Assistant compiles them once an hour, so the card asks again a minute into each hour and every 10 minutes (imported statistics come at any time), the daily ones at most once an hour; cards showing the same meter share the answer. Days and weeks follow the browser's time zone (the server's daily rows are placed on the browser's days) and Home Assistant's first day of the week (the language's when set to automatic).

A utility_meter helper fed by the meter (its source attribute) gives the live value of its period instead of the statistics; without statistics, its last_period attribute is the comparison. A weekly helper starts on Monday, so it is only picked on its own when the week does too (week_entity picks it anyway).

Comparison#

Each period so far is compared with the previous one up to the same point: today until 14:30 against yesterday until 14:30, this week on Thursday at 14:30 against last week until Thursday at 14:30, this month on the 12th against the same time elapsed last month (never past its end: 31 March against all of February), this year against last year. A whole previous period would always look higher early in the period. "So far" means as far as the statistics go: the last compiled hour, or the last day of an import that comes a day or two late (Suez, Gazpar), and the previous period is cut at the same point; a live utility_meter value is compared up to now.

Leak detection#

A small leak (a running toilet, a dripping tap, a broken pipe) keeps the meter turning all night, while a household uses no water for hours. The card looks at the last night window that ended (01:00 – 05:00 by default): when every hour of it used at least the threshold (2 L/h by default), it raises the alert, with last night's lowest hour. Widen the window or raise the threshold if a night appliance (a water softener regeneration, an irrigation program) runs in it. The alert stays until the next night window ends without a continuous flow. While the night is not in the statistics yet (hourly statistics not compiled, an import a day late, daily values only), there is no verdict.

The card can only show the alert while it is on screen: for a notification, use an automation on the same statistics or on a utility_meter helper, or on your leak sensor.

Cost#

price (or price_entity) is per m³ by default — liters are converted — and per kWh with price_unit: energy. A gas meter counting m³ is converted to kWh with conversion_factor (the kWh per m³ on your gas bill, about 11.2 in France); an energy meter priced per m³ is converted the other way. Only the consumption is priced: no subscription or fixed part.

Support

If you find this project useful, you can support its development:

Features

• Utility Meter Card (custom:utility-meter-card) for water and gas meters: index, consumption of the day, the week, the month and the year, each compared with the previous period at the same point, history chart (day, week, month, year) with the previous period behind each bar and the average, details of a bar in a popup at the top of the card.
• Utility Meter Mini Card (custom:utility-meter-mini-card): index, today and this month, the last days as a small chart and the leak alert; its detail button switches it to the full card and back.
• Any sensor with the water or gas device class (pulse counters, Gazpar / GRDF, Suez, Veolia, Eau de Paris…, utility_meter helpers), long-term statistics read with recorder/statistics_during_period, statistic_id for an external statistic; utility_meter helpers fed by the meter found on their own for live values.
• Optional cost: price or price entity, per m³ or per kWh (with a conversion factor for meters counting m³), currency of Home Assistant or your own.
• Leak detection: continuous flow every hour of a configurable night window (water by default), a leak sensor, a daily limit; alert banner, red status pill and night section unfolded.
• Drawn meters animated by their state: the water meter's star wheel spins and water ripples along the pipe while water flows, the gas meter's last digit rolls and its flame flickers, drops fall from the pipe joint on a leak.
• Visual editor for both cards, light and dark themes, 22 languages (English in the bundle, the others loaded on demand).