Vacuum cleaner card for Home Assistant Lovelace UI
Vacuum cleaner card for Home Assistant Lovelace UI
[![npm version][npm-image]][npm-url] [![hacs][hacs-image]][hacs-url] [![GitHub Sponsors][gh-sponsors-image]][gh-sponsors-url] [![Patreon][patreon-image]][patreon-url] [![Buy Me A Coffee][buymeacoffee-image]][buymeacoffee-url] [![Twitter][twitter-image]][twitter-url]
Vacuum cleaner card for [Home Assistant][home-assistant] Lovelace UI
By default, Home Assistant does not provide any card for controlling vacuum cleaners. This card displays the state and allows to control your robot.
![Preview of vacuum-card][preview-image]
** Tip:** If you like this project, consider giving me a tip for the time I spent building this project:
This card is available in [HACS][hacs] (Home Assistant Community Store).
Just search for Vacuum Card in plugins tab.
Download vacuum-card.js file from the [latest-release].
Put vacuum-card.js file into your config/www folder.
Add reference to vacuum-card.js in Lovelace. There's two way to do that:
Using UI: Configuration → Lovelace Dashboards → Resources Tab → Click Plus button → Set Url as /local/vacuum-card.js → Set Resource type as JavaScript Module.
Note: If you do not see the Resources Tab, you will need to enable Advanced Mode in your User Profile
Using YAML: Add following code to lovelace section.
resources:
- url: /local/vacuum-card.js
type: moduleAdd custom:vacuum-card to Lovelace UI as any other card (using either editor or YAML configuration).
This card can be configured using Lovelace UI editor.
entity.Sorry, no support for actions, shortcuts and stats in visual config yet.
Typical example of using this card in YAML config would look like this:
…Here is what every option means:
| Name | Type | Default | Description |
|---|---|---|---|
type |
string |
Required | custom:vacuum-card |
entity |
string |
Required | An entity_id within the vacuum domain. |
battery_entity |
string |
Optional | An entity_id within the sensor domain to display battery state and icon. |
map |
string |
Optional | An entity_id within the camera domain, for streaming live vacuum map. |
map_refresh |
integer |
5 |
Update interval for map camera in seconds |
image |
string |
default |
Path to image of your vacuum cleaner. Better to have png or svg. |
show_name |
boolean |
true |
Show friendly name of the vacuum. |
show_status |
boolean |
true |
Show status of the vacuum. |
show_toolbar |
boolean |
true |
Show toolbar with actions. |
compact_view |
boolean |
false |
Compact view without image. |
stats |
object |
Optional | Custom per state stats for your vacuum cleaner |
actions |
object |
Optional | Override default actions behavior with service invocations. |
shortcuts |
array |
Optional | List of shortcuts shown at the right bottom part of the card with custom actions for your vacuum cleaner. |
stats objectYou can use any attribute of vacuum or even any entity by entity_id to display by stats section. You can also combine attribute with entity_id to extract an attribute value of specific entity:
| Name | Type | Default | Description |
|---|---|---|---|
entity_id |
string |
Optional | An entity_id with state, i.e. sensor.vacuum. |
attribute |
string |
Optional | Attribute name of the stat, i.e. filter_left. |
value_template |
string |
Optional | Jinja2 template returning a value. value variable represents the entity_id or attribute state. |
unit |
string |
Optional | Unit of measure, i.e. hours. |
subtitle |
string |
Optional | Friendly name of the stat, i.e. Filter. |
actions objectYou can defined service invocations to override default actions behavior. Available actions to override are start, pause, resume, stop, locate and return_to_base.
| Name | Type | Default | Description |
|---|---|---|---|
service |
string |
Optional | A service to call, i.e. script.clean_bedroom. |
service_data |
object |
Optional | service_data for service call |
shortcuts objectYou can defined [custom scripts][ha-scripts] for custom actions i.e cleaning specific room and add them to this card with shortcuts option.
| Name | Type | Default | Description |
|---|---|---|---|
name |
string |
Optional | Friendly name of the action, i.e. Clean bedroom. |
service |
string |
Optional | A service to call, i.e. script.clean_bedroom. |
target |
object |
Optional | A HassServiceTarget, to define a target for the current service call. |
icon |
string |
Optional | Any icon for action button. |
service_data |
object |
Optional | service_data for service call |
This card can be styled by changing the values of these CSS properties (globally or per-card via [card-mod][card-mod]):
| Variable | Default value | Description |
|---|---|---|
--vc-background |
var(--ha-card-background, var(--card-background-color, transparent)) |
Card background. |
--vc-primary-text-color |
var(--primary-text-color) |
Vacuum name, stats values, etc. |
--vc-secondary-text-color |
var(--secondary-text-color) |
Status, stats units and titles, etc. |
--vc-icon-color |
var(--secondary-text-color) |
Colors of icons. |
--vc-toolbar-background |
transparent |
Toolbar background (transparent to avoid stacking). |
--vc-toolbar-text-color |
var(--secondary-text-color) |
Color of the toolbar texts. |
--vc-toolbar-icon-color |
var(--secondary-text-color) |
Color of the toolbar icons. |
--vc-divider-color |
var(--entities-divider-color, var(--divider-color)) |
Color of dividers. |
--vc-spacing |
10px |
Paddings and margins inside the card. |
Here is an example of customization via theme. Read more in the Frontend documentation.
my-custom-theme:
vc-background: '#17A8F4'
vc-spacing: 5pxYou can use [card-mod][card-mod] to customize the card on per-card basis, like this:
type: 'custom:vacuum-card'
style: |
ha-card {
--vc-background: #17A8F4;
--vc-spacing: 5px;
}
...I've added some animations for this card to make it alive. Animations are applied only for image property. Here's how they look like:
| Cleaning | Docking |
|---|---|
| ![Cleaning anumation][cleaning-gif] | ![Returning anumation][returning-gif] |
This card supports translations. Please, help to add more translations and improve existing ones. Here's a list of supported languages:
This card relies on basic vacuum services, like pause, start, stop, return_to_base, etc. It should work with any robot vacuum, however I can physically test it only with my own robot vacuum.
If this card works with your vacuum cleaner, please open a PR and your model to the list.
Want to contribute to the project?
No open issues yet, or sync has not completed.