Air Quality Card

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

Features

• Real-time monitoring of CO2, PM2.5, humidity, and temperature
• 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"
• Tap to expand - click any graph to open the full Home Assistant history view
• Visual configuration editor - no YAML required

Installation

HACS (Recommended)

1. Open HACS in Home Assistant
2. Click on "Frontend"
3. Click the three dots in the top right and select "Custom repositories"
4. Add the repository URL: https://github.com/KadenThomp36/air-quality-card
5. Select "Lovelace" as the category
6. Click "Add"
7. Search for "Air Quality Card" and install it
8. Refresh your browser

Manual Installation

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

Configuration

Using the Visual Editor

1. Add a new card to your dashboard
2. Search for "Air Quality Card"
3. Configure the entities using the visual editor

YAML Configuration

type: custom:air-quality-card
name: Office Air Quality
co2_entity: sensor.air_quality_co2
pm25_entity: sensor.air_quality_pm25
humidity_entity: sensor.air_quality_humidity
temperature_entity: sensor.air_quality_temperature
air_quality_entity: sensor.air_quality_index
recommendation_entity: sensor.air_quality_recommendation
hours_to_show: 24
temperature_unit: C

Configuration Options

Option	Type	Required	Default	Description
name	string	No	"Air Quality"	Card title
co2_entity	string	Yes	-	CO2 sensor entity ID
pm25_entity	string	Yes	-	PM2.5 sensor entity ID
humidity_entity	string	No	-	Humidity sensor entity ID
temperature_entity	string	No	-	Temperature sensor entity ID
air_quality_entity	string	No	-	Overall air quality index entity
recommendation_entity	string	No	-	Recommendation template sensor
hours_to_show	number	No	24	Hours of history to display (1-168)
temperature_unit	string	No	"F"	Temperature unit: "F" (Fahrenheit) or "C" (Celsius)

Recommendation Sensor

For the best experience, create a template sensor that provides recommendations. Add this to your configuration.yaml:

template:
  - sensor:
      - name: "Air Quality Recommendation"
        unique_id: air_quality_recommendation
        state: >
          {% set co2 = states('sensor.YOUR_CO2_SENSOR') | float(0) %}
          {% set pm25 = states('sensor.YOUR_PM25_SENSOR') | float(0) %}
          {% set humidity = states('sensor.YOUR_HUMIDITY_SENSOR') | float(0) %}
          {% if co2 > 1500 %}
            Ventilate Now
          {% elif pm25 > 35 %}
            Run Air Purifier
          {% elif pm25 > 25 and co2 > 1000 %}
            Air Purifier + Ventilate
          {% elif pm25 > 25 %}
            Run Air Purifier
          {% elif co2 > 1000 %}
            Open Window
          {% elif humidity < 30 %}
            Too Dry
          {% elif humidity > 60 %}
            Too Humid
          {% elif co2 > 800 or pm25 > 15 %}
            Consider Ventilating
          {% else %}
            All Good
          {% endif %}

Health Thresholds

CO2 (Carbon Dioxide)

Level	Range	Color	Meaning
Excellent	< 600 ppm	Green	Fresh outdoor air levels
Good	600-800 ppm	Light Green	Well-ventilated space
Moderate	800-1000 ppm	Yellow	Acceptable, consider ventilation
Elevated	1000-1500 ppm	Orange	May affect concentration
Poor	> 1500 ppm	Red	Ventilation needed

PM2.5 (Fine Particulate Matter)

Based on WHO 2021 Air Quality Guidelines:

Level	Range	Color	Meaning
Excellent	< 5 µg/m³	Green	WHO annual guideline
Good	5-15 µg/m³	Light Green	WHO 24-hour guideline
Moderate	15-25 µg/m³	Yellow	Slightly elevated
Elevated	25-35 µg/m³	Orange	Consider air purifier
Poor	> 35 µg/m³	Red	Air purifier recommended

Humidity

Level	Range	Color	Meaning
Too Dry	< 30%	Orange	Use humidifier
Dry	30-40%	Light Green	Acceptable
Comfortable	40-50%	Green	Ideal range
Humid	50-60%	Light Green	Acceptable
Too Humid	> 60%	Orange	Improve ventilation

Supported Devices

This card works with any air quality sensor that provides entities for CO2 and PM2.5. Tested with:

• IKEA VINDSTYRKA / ALPSTUGA (via Matter)
• Aqara TVOC Air Quality Monitor
• Xiaomi Air Quality Monitor
• SenseAir S8
• Any ESPHome-based air quality sensor

Development

# 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

Contributing

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

License

MIT License - see LICENSE for details.

Credits

• Thresholds based on WHO 2021 Air Quality Guidelines
• CO2 recommendations based on ASHRAE Standard 62.1