{"id":13801418,"url":"https://github.com/denysdovhan/purifier-card","last_synced_at":"2025-04-08T09:05:29.177Z","repository":{"id":37249659,"uuid":"274738925","full_name":"denysdovhan/purifier-card","owner":"denysdovhan","description":"Air Purifier card for Home Assistant Lovelace UI","archived":false,"fork":false,"pushed_at":"2025-03-31T17:03:04.000Z","size":6777,"stargazers_count":305,"open_issues_count":19,"forks_count":103,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-01T07:45:52.953Z","etag":null,"topics":["air-purifier","custom-cards","hacs","hass","home-assistant","homeassistant","lovelace","purifier","smart-home"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/denysdovhan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"denysdovhan","custom":["buymeacoffee.com/denysdovhan"]}},"created_at":"2020-06-24T18:16:33.000Z","updated_at":"2025-03-16T19:27:49.000Z","dependencies_parsed_at":"2023-12-10T22:28:52.542Z","dependency_job_id":"f0d9fdf0-8e66-4d1e-a4ac-e47a7936b566","html_url":"https://github.com/denysdovhan/purifier-card","commit_stats":{"total_commits":388,"total_committers":38,"mean_commits":"10.210526315789474","dds":0.5257731958762887,"last_synced_commit":"9176a5d916323eb4bb6d46aacbeba45c88f07f0c"},"previous_names":[],"tags_count":51,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denysdovhan%2Fpurifier-card","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denysdovhan%2Fpurifier-card/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denysdovhan%2Fpurifier-card/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denysdovhan%2Fpurifier-card/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/denysdovhan","download_url":"https://codeload.github.com/denysdovhan/purifier-card/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247809963,"owners_count":20999816,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["air-purifier","custom-cards","hacs","hass","home-assistant","homeassistant","lovelace","purifier","smart-home"],"created_at":"2024-08-04T00:01:22.635Z","updated_at":"2025-04-08T09:05:29.170Z","avatar_url":"https://github.com/denysdovhan.png","language":"TypeScript","funding_links":["https://github.com/sponsors/denysdovhan","buymeacoffee.com/denysdovhan","https://www.buymeacoffee.com/denysdovhan","https://patreon.com/denysdovhan"],"categories":["Install from Source","Dashboards"],"sub_categories":["Smart Home Automation","Custom Cards"],"readme":"[![SWUbanner](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner-direct-single.svg)](https://stand-with-ukraine.pp.ua/)\n\n# Purifier Card\n\n[![npm version][npm-image]][npm-url]\n[![hacs][hacs-image]][hacs-url]\n[![GitHub Sponsors][gh-sponsors-image]][gh-sponsors-url]\n[![Patreon][patreon-image]][patreon-url]\n[![Buy Me A Coffee][buymeacoffee-image]][buymeacoffee-url]\n[![Twitter][twitter-image]][twitter-url]\n\n\u003e Air Purifier card for [Home Assistant][home-assistant] Lovelace UI\n\nBy 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.\n\n![Preview of purifier-card][preview-image]\n\n## Installing\n\n**💡 Tip:** If you like this project ~~and want to get some stickers and postcards~~, consider giving me a tip for the time I spent building this project:\n\n\u003ca href=\"https://www.buymeacoffee.com/denysdovhan\" target=\"_blank\"\u003e\n  \u003cimg src=\"https://cdn.buymeacoffee.com/buttons/default-black.png\" alt=\"Buy Me A Coffee\" width=\"150px\"\u003e\n\u003c/a\u003e\n\n### HACS\n\nThis card is available in [HACS][hacs] (Home Assistant Community Store).\n\nJust search for `Purifier Card` in the plugins tab.\n\n### Manual\n\n1. Download `purifier-card.js` file from the [latest-release].\n2. Put `purifier-card.js` file into your `config/www` folder.\n3. Add a reference to `purifier-card.js` in Lovelace. There's two way to do that:\n\n   1. **Using UI:** _Configuration_ → _Lovelace Dashboards_ → _Resources_ → Click Plus button → Set _Url_ as `/local/purifier-card.js` → Set _Resource type_ as `JavaScript Module`.\n   2. **Using YAML:** Add the following code to `lovelace` section.\n\n      ```yaml\n      resources:\n        - url: /local/purifier-card.js\n          type: module\n      ```\n\n4. Add `custom:purifier-card` to Lovelace UI as any other card (using either editor or YAML configuration).\n\n## Using the card\n\nThis card can be configured using Lovelace UI editor.\n\n1. In Lovelace UI, click 3 dots in top left corner.\n2. Click _Configure UI_.\n3. Click Plus button to add a new card.\n4. Find _Custom: Purifier Card_ in the list.\n5. Choose `entity`.\n6. Now you should see the preview of the card!\n\n_Sorry, no support for `shortcuts` and `stats` in visual config yet._\n\nTypical example of using this card in YAML config would look like this:\n\n```yaml\ntype: 'custom:purifier-card'\nentity: fan.purifier\nstats:\n  - attribute: filter_life_remaining\n    unit: '%'\n    subtitle: Filter Remaining\n  - attribute: motor_speed\n    unit: RPM\n    subtitle: Motor Speed\n  - entity_id: sensor.purifier_filter_life\n    value_template: '{{ (value | float(0) / 3600) | round(1) }}'\n    unit: hours\n    subtitle: Filter Life\nshortcuts:\n  - name: Silent\n    icon: 'mdi:weather-night'\n    preset_mode: Silent\n  - name: 25%\n    icon: 'mdi:circle-slice-2'\n    percentage: 25\n  - name: 50%\n    icon: 'mdi:circle-slice-4'\n    percentage: 50\n  - name: 75%\n    icon: 'mdi:circle-slice-6'\n    percentage: 75\n  - name: 100%\n    icon: 'mdi:circle-slice-8'\n    percentage: 100\n  - name: Auto\n    icon: 'mdi:brightness-auto'\n    preset_mode: Auto\nshow_name: true\nshow_state: true\nshow_toolbar: true\ncompact_view: false\n```\n\nHere is what every option means:\n\n| Name               |   Type    | Default      | Description                                      |\n| ------------------ | :-------: | ------------ | ------------------------------------------------ |\n| `type`             | `string`  | **Required** | `custom:purifier-card`                           |\n| `entity`           | `string`  | **Required** | An entity_id within the `fan` domain.            |\n| `show_name`        | `boolean` | `true`       | Show friendly name of the purifier.              |\n| `show_state`       | `boolean` | `true`       | Show state of the purifier.                      |\n| `show_preset_mode` | `boolean` | `true`       | Show preset mode of the purifier in the header.  |\n| `show_toolbar`     | `boolean` | `true`       | Show toolbar with shortcuts.                     |\n| `compact_view`     | `boolean` | `false`      | Compact view without image.                      |\n| `aqi`              | `object`  | Optional     | Custom entity or attribute for AQI value.        |\n| `stats`            |  `array`  | Optional     | Custom per state stats for your purifier cleaner |\n| `shortcuts`        | `object`  | Optional     | Custom shortcuts for your purifier cleaner.      |\n\n### `aqi` object\n\n| Name        |   Type   | Default  | Description                                         |\n| ----------- | :------: | -------- | --------------------------------------------------- |\n| `entity_id` | `string` | Optional | An entity_id with state, i.e. `sensor.current_aqi`. |\n| `attribute` | `string` | Optional | An attribute which should be used to get AQI value. |\n| `unit`      | `string` | Optional | An unit of measurement to display.                  |\n\nYou can also combine `attribute` with `entity_id` to extract an attribute value of specific entity.\n\n### `stats` object\n\nYou can use any attribute of purifier or even any entity by `entity_id` to display by stats section. Not only that, but you can also combine `attribute` with `entity_id` to extract an attribute value of specific entity:\n\n| Name             |   Type   | Default  | Description                                                                                          |\n| ---------------- | :------: | -------- | ---------------------------------------------------------------------------------------------------- |\n| `entity_id`      | `string` | Optional | An entity_id with state, i.e. `sensor.purifier_aqi`.                                                 |\n| `attribute`      | `string` | Optional | Attribute name of the stat, i.e. `filter_left`.                                                      |\n| `value_template` | `string` | Optional | Jinja2 template returning a value. `value` variable represents the `entity_id` or `attribute` state. |\n| `unit`           | `string` | Optional | Unit of measure, i.e. `hours`.                                                                       |\n| `subtitle`       | `string` | Optional | Friendly name of the stat, i.e. `Filter`.                                                            |\n\n### `shortcuts` object\n\nYou can define [custom scripts][ha-scripts] for custom actions or add shortcuts for switching presets and percentages via `shortcuts` option.\n\n| Name           |   Type   | Default  | Description                                                                                     |\n| -------------- | :------: | -------- | ----------------------------------------------------------------------------------------------- |\n| `name`         | `string` | Optional | Friendly name of the shortcut, i.e. `Switch to Auto`.                                           |\n| `icon`         | `string` | Optional | Any icon for shortcut button.                                                                   |\n| `service`      | `string` | Optional | A service to call, i.e. `script.clean_air`.                                                     |\n| `target`       | `object` | Optional | A `HassServiceTarget`, to define a target for the current service call.                         |\n| `service_data` | `object` | Optional | `service_data` for `service` call                                                               |\n| `percentage`   | `object` | Optional | A `percentage` to switch to, i.e. `27`, etc. See `entity`'s `percentage_step` for valid values. |\n| `preset_mode`  | `object` | Optional | A `speed` to switch to, i.e. `Auto`, etc                                                        |\n\nThe card will automatically try to figure out which one of shortcuts is currently active. The shortcut will be highlighted when:\n\n1. It's a service.\n2. `entity`'s `percentage` attribute is equal to `shortcut`'s `percentage`.\n3. `entity`'s `preset_mode` attribute is equal to `shortcut`'s `preset_mode`.\n\n## Theming\n\nThis card can be styled by changing the values of these CSS properties (globally or per-card via [`card-mod`][card-mod]):\n\n| Variable                    | Default value                                                    | Description                          |\n| --------------------------- | ---------------------------------------------------------------- | ------------------------------------ |\n| `--pc-background`           | `var(--ha-card-background, var(--card-background-color, white))` | Background of the card               |\n| `--pc-primary-text-color`   | `var(--primary-text-color)`                                      | Vacuum name, stats values, etc       |\n| `--pc-secondary-text-color` | `var(--secondary-text-color)`                                    | Status, stats units and titles, etc  |\n| `--pc-icon-color`           | `var(--secondary-text-color)`                                    | Colors of icons                      |\n| `--pc-slider-path-color`    | `var(--round-slider-path-color)`                                 | Color of the slider path             |\n| `--pc-slider-bar-color`     | `var(--round-slider-bar-color)`                                  | Color of the slider bar              |\n| `--pc-toolbar-background`   | `var(--vc-background)`                                           | Background of the toolbar            |\n| `--pc-toolbar-text-color`   | `var(--secondary-text-color)`                                    | Color of the toolbar texts           |\n| `--pc-toolbar-icon-color`   | `var(--secondary-text-color)`                                    | Color of the toolbar icons           |\n| `--pc-divider-color`        | `var(--entities-divider-color, var(--divider-color))`            | Color of dividers                    |\n| `--pc-spacing`              | `10px`                                                           | Paddings and margins inside the card |\n\n### Styling via theme\n\nHere is an example of customization via theme. Read more in the [Frontend documentation](https://www.home-assistant.io/integrations/frontend/).\n\n```yaml\nmy-custom-theme:\n  pc-background: '#17A8F4'\n  pc-spacing: 5px\n```\n\n### Styling via card-mod\n\nYou can use [`card-mod`][card-mod] to customize the card on per-card basis, like this:\n\n```yaml\ntype: 'custom:purifier-card'\nstyle: |\n  ha-card {\n    --pc-background: #17A8F4;\n    --pc-spacing: 5px;\n  }\n  ...\n```\n\n## Animations\n\nI've added an animation for this card to make it alive:\n\n\u003cimg src=\"https://raw.githubusercontent.com/denysdovhan/purifier-card/master/src/images/purifier-working.gif\" width=\"300px\"\u003e\n\nHow did I make this animation? It's a long story…\n\n1. I took original gif file from [here][original-gif].\n2. Then I tweaked image levels to make the background black and purifier white.\n3. Then I inverted colors on the gif.\n4. Then I've split the gif by frame.\n5. Then I removed the background of the image frame by frame using remove.bg.\n6. Then I upscaled each of those images using icons8.com/upscaler.\n7. Then I put up all of those images back in a single gif.\n8. Profit!\n\nArchive with images from all of these steps [can be found here](https://t.me/denysandtech/185).\n\n## Supported languages\n\nThis card supports translations. Please, help to add more translations and improve existing ones. Here's a list of supported languages:\n\n- English\n- Українська (Ukrainian)\n- Türkçe (Turkish)\n- Français (French)\n- Norsk (Norwegian)\n- Polski (Polish)\n- Български (Bulgarian)\n- 简体中文 (Simplified Chinese)\n- Deutsch (German)\n- Català (Catalan)\n- Русский (Russian)\n- Italiano (Italian)\n- 繁體中文 (Traditional Chinese)\n- Čeština (Czech)\n- Dutch (Netherlands)\n- Español (Spanish)\n- Slovenčina (Slovak)\n- Português (Portuguese)\n- [_Your language?_][add-translation]\n\n## Supported models\n\nThis 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.\n\nIf this card works with your air purifier, please open a PR and your model to the list (in alphabetical order).\n\n- Air Purifier 4 Pro\n- Air Purifier 3/3H\n- Air Purifier 2/2H/2S\n- Air Purifier Pro\n- Blueair Classic 480i/680i\n- Coway Airmega 300S/400S ([using IoCare custom component](https://github.com/RobertD502/home-assistant-iocare))\n- Dyson Pure Cool/Cool Link/Cool Desk/Cool Link Desk ([using Dyson custom integration](https://github.com/libdyson-wg/ha-dyson))\n- Dyson Pure Humidify+Cool ([using Dyson custom integration](https://github.com/libdyson-wg/ha-dyson))\n- Dyson Purifier Hot+Cool HP2 De-NOx ([using Dyson custom integration](https://github.com/libdyson-wg/ha-dyson))\n- Honeywell H-Cat Air Purifier ([using Local Tuya integration](https://github.com/xZetsubou/hass-localtuya))\n- Ikea Starkvind\n- Levoit Air Purifier (Core 200S) (partially)\n- Levoit Air Purifier (Core 400S)\n- Philips AirPurifier AC3858/50 (partially)\n- Philips AirPurifier AC4221/11 ([using philips-airpurifier-coap cutom component](https://github.com/kongo09/philips-airpurifier-coap))\n- SmartMI Air Purifier\n- Winix AM90 Wi-Fi Air Purifier\n- [_Your purifier?_][edit-readme]\n\n## Development\n\nWant to contribute to the project?\n\nFirst of all, thanks! Check [contributing guideline](./CONTRIBUTING.md) for more information.\n\n## Inspiration\n\nThis project is heavily inspired by:\n\n- [MacBury Smart House][macbury-smart-house] — basically, this project is a refinement of MacBury's custom card.\n\nHuge thanks for their ideas and efforts 👍\n\n## License\n\nMIT © [Denys Dovhan][denysdovhan]\n\n\u003c!-- Badges --\u003e\n\n[npm-url]: https://npmjs.org/package/purifier-card\n[npm-image]: https://img.shields.io/npm/v/purifier-card.svg?style=flat-square\n[hacs-url]: https://github.com/hacs/integration\n[hacs-image]: https://img.shields.io/badge/hacs-default-orange.svg?style=flat-square\n[gh-sponsors-url]: https://github.com/sponsors/denysdovhan\n[gh-sponsors-image]: https://img.shields.io/github/sponsors/denysdovhan?style=flat-square\n[patreon-url]: https://patreon.com/denysdovhan\n[patreon-image]: https://img.shields.io/badge/support-patreon-F96854.svg?style=flat-square\n[buymeacoffee-url]: https://patreon.com/denysdovhan\n[buymeacoffee-image]: https://img.shields.io/badge/support-buymeacoffee-222222.svg?style=flat-square\n[twitter-url]: https://twitter.com/denysdovhan\n[twitter-image]: https://img.shields.io/badge/twitter-%40denysdovhan-00ACEE.svg?style=flat-square\n\n\u003c!-- References --\u003e\n\n[home-assistant]: https://www.home-assistant.io/\n[hacs]: https://hacs.xyz\n[preview-image]: https://user-images.githubusercontent.com/3459374/164275676-504d92aa-2c61-4451-ae9b-23dad113ce14.png\n[latest-release]: https://github.com/denysdovhan/purifier-card/releases/latest\n[ha-scripts]: https://www.home-assistant.io/docs/scripts/\n[xiaomi-miio-favorite-levels]: https://www.home-assistant.io/integrations/xiaomi_miio/#service-xiaomi_miiofan_set_favorite_level-air-purifiers-only\n[original-gif]: https://github.com/macbury/SmartHouse/blob/master/home-assistant/www/custom-lovelace/air-purifier/standby.gif\n[edit-readme]: https://github.com/denysdovhan/purifier-card/edit/master/README.md\n[add-translation]: https://github.com/denysdovhan/purifier-card/blob/master/CONTRIBUTING.md#how-to-add-translation\n[macbury-smart-house]: https://macbury.github.io/SmartHouse/HomeAssistant/Lovelace/#air-purifier\n[denysdovhan]: https://denysdovhan.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdenysdovhan%2Fpurifier-card","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdenysdovhan%2Fpurifier-card","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdenysdovhan%2Fpurifier-card/lists"}