Pool Card

Features

• Two cards: a full Pool Card (custom:pool-card) and a compact Pool Mini Card (custom:pool-mini-card), for a pool or a spa (kind, guessed from the name)
• Animated scene of the pool (or of the round spa) on its deck: the water ripples and a current crosses it while the pump filters, bubbles rise in a spa, the heat pump spins its fan and its flame flickers while it heats, the underwater light glows in its color, the roller cover unrolls and rolls back; the water turns teal on a critical value and green when the disinfection is too low (see Animations)
• Header icon (pool or spa) in a round badge colored with the water status, and a status pill on the title line: Water OK, Check the water, Action needed; its dot blinks while something runs
• Big water temperature with the air temperature, heating and cover state next to the scene
• Colored gauges for water temperature, pH, ORP, free chlorine, salt and TDS: the ideal range in green, a warning margin in orange, critical beyond it in red (cold water in blue), the value marked on it, the ideal range written under it; all ranges configurable (ranges), in the unit of each sensor (°C or °F, g/L or ppm)
• Advice for every value out of its range (pH too high: add pH minus…) and for equipment running without water flow (heat pump heating or electrolyser on while the pump is stopped)
• Filtration: pump state, speed buttons (select or fan presets), time filtered today against a daily target (the filtration_hours option, iopool's recommendation, or the classic rule water temperature ÷ 2), from a sensor or computed from the pump's history
• Control buttons for the pump, the light, the heat pump, the cover and the electrolyser; heat pump target with − / + buttons; stopping the pump while the heat pump heats (pump button, or the off option of its speed select) asks for a confirmation (popup at the top of the card, Cancel focused)
• Collapsible sections (advice, filtration, equipment; equipment folded by default), folded back by a click anywhere else on the page
• 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); buttons disabled while their entity is unavailable
• 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, the scene is drawn by the card itself

Supported integrations

The card reads standard Home Assistant entities: any integration exposing them works. Those below are the usual ones; their entities are found from the device when you pick it.

Integration	Devices	What the cards show
iopool (custom)	iopool ECO probe	Water temperature, pH, ORP, filtration recommendation (target of the day), filtration state (its Filtration binary sensor: the time of the day is computed from its history)
Blue Riiot / Blue Connect — through BlueRiiot2MQTT or an ESPHome BLE bridge	Blue Connect, Blue Connect Go	Water temperature, pH, ORP, salinity
ESPHome (core)	DIY probes and controllers (Atlas Scientific, DFRobot…), spa controllers	Any sensor, switch, select, climate, light and cover, recognized from their names (ph, orp, chlorine, salt, tds, pump, light…)
Pentair ScreenLogic (core)	ScreenLogic, IntelliChem, IntelliChlor, IntelliFlo	Air temperature, pH, ORP and salt (IntelliChem and IntelliChlor sensors, filed as diagnostic but found all the same), pool / spa heaters (climate; their current temperature is the water temperature), lights. The filter pump runs with the Pool circuit: set that switch as pump
Pentair IntelliCenter (custom)	IntelliCenter	Water and air temperature, heaters, pump state (binary sensor; set the Pool body switch as pump to command it), lights, pH, ORP, salt
Hayward OmniLogic (core)	OmniLogic, OmniHub	Water and air temperature, pH, ORP, salt level, filter pump (switch), chlorinator output (electrolyser)
Jandy iAquaLink (core)	iAquaLink	Pool / spa heaters (climate), water and air temperature, pump and aux switches, lights
Any other	Shelly / Sonoff switches, history_stats, template sensors, helpers	Set each entity in the options: pump, speed, heat pump, electrolyser, light, cover, sensors

How the card recognizes each entity is detailed in How it works.

Prerequisites

Home Assistant 2024.8 or later, with the pool's sensors available as entities (see Supported integrations). The filtration time computed from the pump's history needs the pump to be recorded (the default).

Configuration

Card types#

Visual editor#

Edit a dashboard, click Add card and search for Pool Card or Pool Mini Card. The device with the most water quality sensors is preselected; pick another one, set the entities the device does not have under Entities (the pump of another brand, the heat pump, the cover…), the ideal ranges, the daily filtration target, the sections and the language. The preview updates live, and options left at their default are kept out of the generated YAML.

Minimal#

type: custom:pool-card

type: custom:pool-mini-card

Without any option, the card takes the device with the most water quality sensors.

Full options#

type: custom:pool-card
device: Pool
title: Pool
kind: pool
# Entities: each one replaces what the device gives (or completes it)
water_temperature: sensor.pool_temperature
air_temperature: sensor.outdoor_temperature
ph: sensor.pool_ph
orp: sensor.pool_orp
chlorine: sensor.pool_free_chlorine
salt: sensor.pool_salt
tds: sensor.pool_tds
pump: switch.filtration_pump
pump_speed: select.pump_speed
filtration_time: sensor.filtration_today
filtration_target: sensor.pool_filtration_recommendation
heat_pump: climate.pool_heat_pump
electrolyser: switch.pool_electrolyser
light: light.pool_light
cover: cover.pool_cover
filtration_hours: 10
ranges:
  ph_min: 7.0
  ph_max: 7.4
  orp_min: 700
  orp_max: 780
  chlorine_min: 1
  chlorine_max: 2
  salt_min: 4
  salt_max: 6
  water_temperature_min: 26
  water_temperature_max: 29
show_title: true
show_subtitle: true
show_controls: true
show_advice: true
show_filtration: true
show_equipment: true
collapsed:
  - equipment
language: fr

type: custom:pool-mini-card
device: Garden spa
kind: spa
show_controls: true
zoom: true

Options reference#

Default ideal ranges#

These follow the CDC (free chlorine at least 1 ppm in a pool and 3 ppm in a hot tub, pH 7.0–7.8), the CDC Model Aquatic Health Code (ORP 600–900 mV, chlorine 10 ppm at most), the WHO (ORP around 720 mV) and the US hot tub limit of 40 °C (104 °F). The salt range depends on the electrolyser: a sensor in ppm (Pentair, Hayward and Jandy controllers) gets the 2700–3400 ppm of their cells, one in g/L the 3–5 g/L of most European ones. The TDS of a salt pool includes its salt, so its ideal maximum is the salt level plus 1500 ppm (3000 ppm assumed with an electrolyser and no salt sensor).

Temperatures in °F are converted. Set your own ideal ranges with ranges (or Ideal ranges in the visual editor), for instance the salt range of your electrolyser's manual.

How it works

With a device, the card goes through the entities of that device in the Home Assistant entity registry and gives each one a role from its domain, device class, unit and names (entity id, translation key, names; the English names of the integrations, and a few French, German and Spanish words for ESPHome and template entities):

Configuration, disabled and hidden entities are left out, and so are diagnostic ones except water measures (ScreenLogic files its chemistry sensors there). Any role set in the options replaces the discovered one, so the card also works with no device at all, entity by entity.

The status is the worst level of the water quality gauges (a cold water counts as in range) and of the advice. The filtration time of the day comes from the filtration_time sensor, or else from the pump's history since midnight (read with the history/history_during_period websocket command at most every 5 minutes and whenever the pump changes state, the time since added while it runs). The target is filtration_hours, else the filtration_target sensor, else, for a pool, half the water temperature in °C (27 °C → 13.5 h, rounded to the degree).

Support

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

Features

• Pool Card (custom:pool-card): animated pool or spa scene (water rippling while the pump filters, spa bubbles, heat pump fan and flame while it heats, underwater light glowing in its color, roller cover unrolling and rolling back, the water turning green when the disinfection is too low), water temperature, air temperature, colored gauges with ideal ranges for pH, ORP, free chlorine, salt, TDS and water temperature, advice for every value out of its range and for equipment running without water flow, filtration state, speed and time of the day against a daily target, control buttons and an equipment section (heat pump target, electrolyser, cover, light).
• Pool Mini Card (custom:pool-mini-card): compact summary (scene, values with their level, filtration of the day, first advice, pump and light buttons) with a detail button that switches to the full card.
• Entities discovered from a device (iopool, ESPHome, Pentair ScreenLogic and IntelliCenter, Hayward OmniLogic, Jandy iAquaLink, Blue Riiot through MQTT…), whatever their ids or language, each one replaceable in the options; pump as a switch, a select (speeds) or a fan (presets).
• Filtration time of the day from a sensor (a history_stats sensor, a controller's counter) or computed from the pump's history; target from the options, from iopool's recommendation or water temperature ÷ 2.
• Ideal ranges configurable per measure (ranges), in the unit of each sensor (°C / °F, g/L / ppm).
• Stopping the pump while the heat pump heats (pump button, or the off option of its speed select) asks for a confirmation (popup at the top of the card, Cancel focused).
• Default ideal ranges after the CDC, the CDC MAHC and the WHO, with spa-specific chlorine and temperature, salt per unit (ppm for US controllers, g/L for European cells) and a salt pool's TDS including its salt.
• Visual editor for both cards, 22 languages (English in the bundle, the others loaded on demand), light and dark themes, prefers-reduced-motion honoured.