A Home Assistant Lovelace card with a clean dashboard look to display air quality & comfort at a glance
(CO₂, VOC, radon, CO, CH₂O, pressure, temperature, humidity… from airthings, netatmo, Xiaomi and others devices ) with a colored gauge, a status label, an optional AQI summary, and an integrated history graph.
Note
This module supports values from any Home Assistant–compatible sensor, so you can display and interpret indoor air quality from all your entities in one unified card.
...
JP2 AAir Quality Card is available in HACS (Home Assistant Community Store).
Use this link to directly go to the repository in HACS
- Copy
jp2-air-quality.jsto:/config/www/(Lovelace path is/local/)
- Add Lovelace resource:
- Settings → Dashboards → Resources → Add
- URL:
/local/jp2-air-quality.js - Type:
Module
- Hard refresh the browser
Important
The main file must stay named exactly jp2-air-quality.js.
type: custom:jp2-air-quality
title: Air quality
entities:
radon: sensor.radon_bq_m3
co2: sensor.co2_ppm
voc: sensor.voc_ppb
pressure: sensor.pressure_hpa
temperature: sensor.temperature_salon
humidity: sensor.humidity_salon
Minimal card (only CO₂)
type: custom:jp2-air-quality
title: Living room
entities:
co2: sensor.living_room_co2Graph enabled (24h)
type: custom:jp2-air-quality
title: Living room
show_graph: true
graph_hours: 24
entities:
co2: sensor.living_room_co2
temperature: sensor.living_room_temperature
humidity: sensor.living_room_humidityAQI summary (with thresholds)
type: custom:jp2-air-quality
title: Living room
aqi:
enabled: true
hide_sensors: false
sensors:
- entity: sensor.living_room_co2
label: CO2
unit: ppm
good: 800
medium: 1200
- entity: sensor.living_room_voc
label: VOC
unit: ppb
good: 150
medium: 300
entities:
co2: sensor.living_room_co2
voc: sensor.living_room_voc
temperature: sensor.living_room_temperature
humidity: sensor.living_room_humidityAQI mode — hide the sensor list
type: custom:jp2-air-quality
title: Living room
aqi:
enabled: true
hide_sensors: true
sensors:
- entity: sensor.living_room_co2
label: CO2
unit: ppm
good: 800
medium: 1200
- entity: sensor.living_room_voc
label: VOC
unit: ppb
good: 150
medium: 300
entities:
co2: sensor.living_room_co2
voc: sensor.living_room_vocAQI mode — horizontal layout + icons only
[!TIP]
This mode is perfect for a compact “summary row”.
type: custom:jp2-air-quality
title: Living room
aqi:
enabled: true
layout: horizontal
icons_only: true
sensors:
- entity: sensor.living_room_co2
label: CO2
unit: ppm
good: 800
medium: 1200
- entity: sensor.living_room_voc
label: VOC
unit: ppb
good: 150
medium: 300
- entity: sensor.living_room_radon
label: Radon
unit: Bq/m³
good: 100
medium: 300
entities:
co2: sensor.living_room_co2
voc: sensor.living_room_voc
radon: sensor.living_room_radonAQI title — add an image and/or an icon on the left
type: custom:jp2-air-quality
title: Living room
aqi:
enabled: true
# Left of “AQI”
title_icon: mdi:air-filter
title_image: /local/icons/air-quality.png
sensors:
- entity: sensor.living_room_co2
label: CO2
unit: ppm
good: 800
medium: 1200
entities:
co2: sensor.living_room_co2Icon styling (no background + no ring)
type: custom:jp2-air-quality
title: Living room
icon:
size: 44
show_background: false
show_circle: false
entities:
co2: sensor.living_room_co2
temperature: sensor.living_room_temperature
humidity: sensor.living_room_humidity| Name | Type | Default | Description |
|---|---|---|---|
title |
string | — | Card title |
entities |
object | — | Sensors mapping: co2, voc, radon, pressure, temperature, humidity… |
| Name | Type | Default | Description |
|---|---|---|---|
show_graph |
boolean | false |
Enable built-in history graph |
graph_hours |
number | 24 |
History window in hours |
| Name | Type | Default | Description |
|---|---|---|---|
icon.size |
number | 44 |
Icon size (px) |
icon.show_background |
boolean | true |
Show/hide icon background |
icon.show_circle |
boolean | true |
Show/hide icon ring |
| Name | Type | Default | Description |
|---|---|---|---|
aqi.enabled |
boolean | false |
Enable AQI summary mode |
aqi.hide_sensors |
boolean | false |
Hide the sensor list in AQI mode |
aqi.layout |
string | vertical |
AQI layout (vertical / horizontal) |
aqi.icons_only |
boolean | false |
In horizontal layout: only show icons (hide the rest) |
aqi.title_icon |
string | — | Optional left icon (e.g. mdi:air-filter) |
aqi.title_image |
string | — | Optional left image (e.g. /local/...png) |
aqi.sensors |
array | [] |
AQI sensors list with thresholds |
| Field | Type | Required | Description |
|---|---|---|---|
entity |
string | ✅ | HA entity (ex: sensor.co2_ppm) |
label |
string | ✅ | Display name |
unit |
string | ❌ | Display unit (ppm/ppb/…) |
good |
number | ✅ | “Good” threshold |
medium |
number | ✅ | “Medium” threshold (above = “Bad”) |
Important
If you previously used the iqa: key, update it to aqi:.
V2+ includes a full redesign of the visual editor:
- smoother UI / fewer freezes
- clearer settings sections
- more stable behavior when enabling AQI and/or Graph
- cleaner internal structure for easier maintenance
- Check the resource path (
/local/...or/hacsfiles/...) - Ensure the resource type is Module
- Hard refresh the browser
- Clear browser cache
- Or use a cache buster:
/local/jp2-air-quality.js?v=2
- Recorder/history must be enabled
- The entity state must be numeric
- Update to the latest version (includes stability improvements and visual editor updates)
Copy jp2-air-quality.js into /config/www/
Add resource: /local/jp2-air-quality.js?v=dev
Hard refresh browser after each change.
Tip: keeping ?v=dev helps bypass cache while iterating.
Please open an Issue with:
- Home Assistant version
- YAML config (remove sensitive info)
- Console logs (F12)
PR workflow:
- Fork
- Create a branch:
feature/my-feature - Clean commits
- Pull Request
See GitHub releases: Releases
MIT — see LICENSE.
If this project helps you, you can support it here: Buy me a coffee