A custom Home Assistant Lovelace card for monitoring indoor air quality with beautiful gradient graphs and WHO-based health thresholds.

• Features
• Installation
• Configuration
• Built-in Recommendations
• Health Thresholds
• Supported Devices
• Development
• Other Cards
• Star History
• Support

• Real-time monitoring of CO, Radon, CO2, PM2.5, PM10, PM1, PM0.3, HCHO, tVOC, humidity, and temperature
• CO safety alerts -- critical red warnings for dangerous carbon monoxide levels
• Radon advisory banner -- separate long-term health advisory with EPA/WHO thresholds (supports pCi/L and Bq/m3)
• Gradient-colored graphs that change color based on air quality levels
• Interactive hover/touch to see historical values at any point
• Health-based thresholds following WHO 2021 guidelines and ASHRAE standards
• Actionable recommendations like "Open Window" or "Run Air Purifier"
• Outdoor sensor comparison - optional dashed line overlay with smart ventilation recommendations
• Tap to expand - click any graph to open the full Home Assistant history view
• Visual configuration editor - no YAML required, with collapsible sections for clean organization

Or manually: open HACS, search for "Air Quality Card", click Install, and refresh your browser.

1. Download air-quality-card.js from the latest release
2. Copy it to /config/www/air-quality-card/air-quality-card.js
3. Add the resource in Home Assistant:
   • Go to Settings → Dashboards → Resources
   • Add /local/air-quality-card/air-quality-card.js as a JavaScript Module

1. Add a new card to your dashboard
2. Search for "Air Quality Card"
3. Configure the entities using the visual editor
4. Primary sensors (CO₂, PM2.5, Humidity, Temperature) are always visible
5. Expand "Additional Sensors" for Radon, CO, HCHO, tVOC, PM1, PM10, PM0.3
6. Expand "Outdoor Sensors" for comparison data

type: custom:air-quality-card
name: Office Air Quality
co2_entity: sensor.air_quality_co2
pm25_entity: sensor.air_quality_pm25
pm10_entity: sensor.air_quality_pm10
co_entity: sensor.air_quality_co
radon_entity: sensor.wave_1_day_average
radon_longterm_entity: sensor.wave_longterm_average
humidity_entity: sensor.air_quality_humidity
temperature_entity: sensor.air_quality_temperature
air_quality_entity: sensor.air_quality_index
hours_to_show: 24
temperature_unit: C
outdoor_co2_entity: sensor.outdoor_co2
outdoor_pm25_entity: sensor.outdoor_pm25

* At least one sensor entity is required. Use any combination that fits your setup.

Configure outdoor sensor entities to see a dashed comparison line on each graph showing outdoor conditions alongside indoor readings. When outdoor sensors are configured:

• A subtle dashed line appears on the corresponding graph
• Hovering shows both indoor and outdoor values
• Current outdoor values appear next to indoor readings
• Smart recommendations avoid suggesting ventilation when outdoor air is worse (e.g., "Keep Windows Closed" instead of "Open Window")

The card automatically generates actionable recommendations based on your sensor readings -- no template sensors needed. It evaluates CO, CO2, PM2.5, PM10, HCHO, tVOC, and humidity levels, and when outdoor sensors are configured, it avoids suggesting ventilation when outdoor air is worse.

CO safety alerts are always shown regardless of outdoor conditions -- carbon monoxide is a life-safety concern. If CO exceeds dangerous levels, the card shows a critical red warning with instructions to leave the area.

Radon advisory banner appears as a separate element below the main recommendation when radon levels are elevated. Unlike other pollutants, radon changes over days/weeks and requires professional mitigation (not "open a window"), so it uses its own advisory system instead of the main recommendation waterfall. The advisory shows at three levels: informational (approaching action level), warning (above EPA action level of 4.0 pCi/L / 148 Bq/m3), and danger (significantly elevated, mitigation needed).

Based on EPA and WHO guidelines:

Based on WHO 2021 Air Quality Guidelines:

Based on WHO 2021 Air Quality Guidelines:

This card works with any sensor that provides entities for CO, Radon, CO2, PM2.5, PM10, PM1, PM0.3, HCHO, tVOC, humidity, or temperature. Use any combination -- even a single sensor works. Tested with:

• IKEA VINDSTYRKA / ALPSTUGA (via Matter)
• Aqara TVOC Air Quality Monitor
• Xiaomi Air Quality Monitor
• SenseAir S8
• AirGradient ONE / Open Air
• PurpleAir sensors
• Airthings Wave / Wave Plus (radon, CO2, tVOC, humidity, temperature)
• Any ESPHome-based air quality sensor

# Clone the repository
git clone https://github.com/KadenThomp36/air-quality-card.git

# The card is vanilla JavaScript with no build step required
# Simply edit air-quality-card.js and test in Home Assistant

# Run tests
node test.js

Contributions are welcome! Please feel free to submit a Pull Request.

MIT License - see LICENSE for details.

If you like this card, check out my other Home Assistant cards:

• Garage Card — A top-down visual garage card with door state, car presence, and light control

If you find this card useful, consider buying me a coffee!

• Thresholds based on WHO 2021 Air Quality Guidelines
• CO2 recommendations based on ASHRAE Standard 62.1
• CO thresholds based on EPA/WHO carbon monoxide guidelines