1.0.1 • Published 2 months ago

purifier-card v1.0.1

Weekly downloads
Last release
2 months ago

Purifier Card

npm version hacs Patreon Buy Me A Coffee Twitter

Air Purifier card for Home Assistant Lovelace UI

By default, the Home Assistant does not provide any card for controlling air purifiers. This card displays the state and allows to control your air purifier.

Preview of purifier-card


💡 Tip: If you like this project and want to get some stickers and postcards, consider becoming a patron:

or just buy me a cup of ☕️ or 🥤:


This card is available in HACS (Home Assistant Community Store).

Just search for Purifier Card in the plugins tab.


  1. Download purifier-card.js file from the latest-release.
  2. Put purifier-card.js file into your config/www folder.
  3. Add a reference to purifier-card.js in Lovelace. There's two way to do that:
    1. Using UI: ConfigurationLovelace DashboardsResources → Click Plus button → Set Url as /local/purifier-card.js → Set Resource type as JavaScript Module.
    2. Using YAML: Add the following code to lovelace section.
        - url: /local/purifier-card.js
          type: module
  4. Add custom:purifier-card to Lovelace UI as any other card (using either editor or YAML configuration).

Using the card

This card can be configured using Lovelace UI editor.

  1. In Lovelace UI, click 3 dots in top left corner.
  2. Click Configure UI.
  3. Click Plus button to add a new card.
  4. Find Custom: Purifier Card in the list.
  5. Choose entity.
  6. Now you should see the preview of the card!

Sorry, no support for shortcuts and stats in visual config yet.

Typical example of using this card in YAML config would look like this:

type: 'custom:purifier-card'
entity: fan.purifier
  - attribute: filter_life_remaining
    unit: '%'
    subtitle: Filter Remaining
  - attribute: motor_speed
    unit: RPS
    subtitle: Motor Speed
  - name: Silent
    icon: 'mdi:weather-night'
    speed: Silent
  - name: 25%
    icon: 'mdi:circle-slice-2'
    speed: Favorite
    xiaomi_miio_favorite_level: 3
  - name: 50%
    icon: 'mdi:circle-slice-4'
    speed: Favorite
    xiaomi_miio_favorite_level: 7
  - name: 75%
    icon: 'mdi:circle-slice-6'
    speed: Favorite
    xiaomi_miio_favorite_level: 10
  - name: 100%
    icon: 'mdi:circle-slice-8'
    speed: Favorite
    xiaomi_miio_favorite_level: 14
  - name: Auto
    icon: 'mdi:brightness-auto'
    speed: Auto
show_name: true
show_state: true
show_toolbar: true
compact_view: false

Here is what every option means:

entitystringRequiredAn entity_id within the fan domain.
show_namebooleantrueShow friendly name of the purifier.
show_statusbooleantrueShow status of the purifier.
show_speedbooleanfalseShow speed of the purifier in the header.
show_preset_modebooleantrueShow preset mode of the purifier in the header.
show_toolbarbooleantrueShow toolbar with shortcuts.
compact_viewbooleanfalseCompact view without image.
aqiobjectOptionalCustom entity or attribute for AQI value.
statsobjectOptionalCustom per state stats for your purifier cleaner
shortcutsobjectOptionalCustom shortcuts for your purifier cleaner.
platformstringOptionalDefault 'xiaomi_miio', for Xiaomi Mi Air Purifier & Xiaomi Mi Air Humidifier Integration you must specify xiaomi_miio_airpurifier

aqi object

entity_idstringOptionalAn entity_id with state, i.e. sensor.current_aqi.
attributestringOptionalAn attribute which should be used to get AQI value.
unitstringOptionalAn unit of measurement to display.

stats object

You can use any attribute of purifier or even any entity by entity_id to display by stats section:

entity_idstringOptionalAn entity_id with state, i.e. sensor.purifier_aqi.
attributestringOptionalAttribute name of the stat, i.e. filter_left.
unitstringOptionalUnit of measure, i.e. hours.
subtitlestringOptionalFriendly name of the stat, i.e. Filter.

shortcuts object

You can define custom scripts for custom actions or add shortcuts for switching modes and speeds via shortcuts option.

namestringOptionalFriendly name of the shortcut, i.e. Switch to Auto.
iconstringOptionalAny icon for shortcut button.
servicestringOptionalA service to call, i.e. script.clean_air.
service_dataobjectOptionalservice_data for service call
speedobjectOptionalA speed to switch to, i.e. Auto, etc
xiaomi_miio_favorite_levelobjectOptionalA favorite level of the operation mode Favorite for Xioami Air Purifiers. speed is required with this option

The card will automatically try to figure out which one of shortcuts is currently active. The shortcut will be highlighted when:

  1. It's a service.
  2. entity's speed attribute is equal to shortcut's speed.
  3. entity's speed attribute and favorite_level is equal to shortcut's speed and xiaomi_miio_favorite_level correspondingly.


I've added an animation for this card to make it alive:

How did I make this animation? It's a long story…

  1. I took original gif file from here.
  2. Then I tweaked image levels to make the background black and purifier white.
  3. Then I inverted colors on the gif.
  4. Then I've split the gif by frame.
  5. Then I removed the background of the image frame by frame using remove.bg.
  6. Then I upscaled each of those images using icons8.com/upscaler.
  7. Then I put up all of those images back in a single gif.
  8. Profit!

Archive with images from all of these steps can be found here.

Supported languages

This card supports translations. Please, help to add more translations and improve existing ones. Here's a list of supported languages:

  • English
  • Українська (Ukrainian)
  • Türkçe (Turkish)
  • Français (French)
  • Norsk (Norwegian)
  • Polski (Polish)
  • Български (Bulgarian)
  • 简体中文 (Simplified Chinese)
  • Deutsch (German)
  • Català (Catalan)
  • Русский (Russian)
  • Italiano (Italian)
  • 繁體中文 (Traditional Chinese)
  • Your language?

Supported models

This card relies on basic fan services, like toggle, turn_on, turn_off, etc. It should work with any air purifier, however I can physically test it only with my own purifier.

If this card works with your air purifier, please open a PR and your model to the list.


Want to contribute to the project?

First of all, thanks! Check contributing guideline for more information.


This project is heavily inspired by:

Huge thanks for their ideas and efforts 👍


MIT © Denys Dovhan


2 months ago


2 months ago


2 months ago


4 months ago


4 months ago


5 months ago


5 months ago


5 months ago


5 months ago


6 months ago


6 months ago


9 months ago


10 months ago


10 months ago


12 months ago


12 months ago


12 months ago


12 months ago


1 year ago


1 year ago


1 year ago


1 year ago


1 year ago


1 year ago


1 year ago