Vacuum Card

Features

• Two cards: a full Vacuum Card (custom:vacuum-card) and a compact Vacuum Mini Card (custom:vacuum-mini-card)
• Robot vacuums and wet-dry vacuums, several devices supported, Roborock dock merged with its robot
• Drawn device picture that follows the model (about 130 Roborock, Xiaomi / Mijia, Dreame, Ecovacs, Dyson and iRobot models recognized, see Recognized models from their model id, even when the device was renamed), animated by what the robot is doing, white or dark (color), or your own picture
• Header icon of the kind of device (robot vacuum, mopping robot or wet-dry vacuum) with the brand logo (Roborock, Xiaomi, Mi Home, Dreame, Ecovacs, Dyson or iRobot) as a badge, opening the brand's site, and buttons in the brand's color, readable in the light and dark themes
• The header icon takes the color of the device state, the worst of the robot status, the water tanks and the consumables: red on an error, offline, an empty clean water tank, a full dirty water tank, an empty cleaning fluid tank or a worn-out consumable; orange when paused, a water tank is at 25 % or less or a consumable is nearly due; otherwise the color of the status (blue cleaning, green docked or charging, grey idle). Without a status, it keeps the brand color
• Battery (sensor, or the vacuum's attribute when the integration has no sensor), status, current room, cleaning progress and errors
• Cleaning settings: mode, suction power, mop intensity and route
• Start / pause, stop, return to dock and locate buttons
• Maintenance: main brush, side brush, filter, sensors, mop, dock strainer… with remaining time or percentage, and a reset button (with confirmation) when the integration provides one
• Statistics: last clean, number of cleanings, total area and time
• Map of the current floor while the robot is cleaning (or always, or never), with optional cropping, enlarged full screen on click; any camera or image entity can be used (map_entity)
• Room selector on the Start button: Roborock, Dreame Vacuum, and Xiaomi Miio with the rooms option (see Room selection)
• Roborock: routines of the Roborock app as one-tap buttons, dock (water tanks, detergent, auto-empty mode, mop drying, Empty bin / Wash mop / Dry mop buttons)
• Collapsible sections (statistics and dock folded by default)
• Sections view: the full card takes 12 columns by default and at least 9, the mini card 6; narrow widths get their own layout (see Screenshots)
• Command buttons disabled while the vacuum is unavailable
• Detail button on the mini card (top right): it switches the mini card to the full card's content and back; a click anywhere outside the card brings the compact view back
• Click any value to open its Home Assistant history (more-info dialog)
• Visual editor in the dashboard UI for both cards (no YAML needed)
• Light and dark mode, English, French, German, Spanish, Serbian (Cyrillic and Latin), Italian, Dutch, European Portuguese, Polish, Romanian, Danish, Swedish, Bulgarian, Russian, Ukrainian, Hungarian, Slovak, Czech, Slovenian, Latvian and Greek
• Single file, no external dependency, the logos and pictures are embedded

Supported integrations

Integration	Brands	What the cards show
Roborock (core)	Roborock, Mi Robot Vacuum (1S…)	Everything: status, room, progress, modes, controls, room selector, routines, dock, maintenance with reset, statistics, map
Xiaomi Miio (core)	Roborock and Xiaomi robots paired with Mi Home	Status, errors, fan speed, controls, maintenance with reset, statistics; room selector with the rooms option; map with map_entity
Xiaomi Home (custom)	Xiaomi / Mijia robots	Vacuum (status, fan speed, controls) and battery
Dreame Vacuum (custom)	Dreame, Xiaomi / Mijia robots built by Dreame	Status, room, progress, errors, controls, room selector, maintenance (mop included) with reset, statistics, map
Ecovacs (core)	Ecovacs DEEBOT	Status, errors, cleaning mode and water amount, controls, maintenance in % (mop included) with reset, statistics, map
Dyson (custom, dyson_local)	Dyson 360 Eye, 360 Heurist, 360 Vis Nav	Vacuum (status, power mode, controls) and battery
iRobot Roomba and Braava (core, roomba)	iRobot Roomba (600, 900, e, i, s, j, Combo) and Braava jet m6	Status (Clean Base emptying the bin included), battery, current clean, errors and bin full, fan speed or mopping behavior, water tanks, controls, statistics

Only robot vacuums and wet-dry vacuums are listed: the other devices of these integrations (fans, purifiers, air conditioners, lamps, mowers, the Roborock Zeo washing machine…) are skipped. Details in Integrations.

Prerequisites

Home Assistant 2024.8 or later, with at least one of the supported integrations configured.

Configuration

Card types#

The former types are identical (same options, same editor), whatever the brand of the robot: existing dashboards keep working.

Note

custom:vacuum-card is also the type of denysdovhan/vacuum-card. When both are installed, the one loaded first gets vacuum-card; use custom:robot-vacuum-card / custom:robot-vacuum-mini-card for this one, they are always available.

Visual editor#

Edit a dashboard, click Add card and search for Vacuum Card or Vacuum Mini Card. The first robot vacuum is preselected; pick another device in the list if you have several, set an optional title, choose the picture and its color, the sections to display and the language. The preview updates live, and options left at their default are kept out of the generated YAML.

Minimal#

type: custom:vacuum-card

type: custom:vacuum-mini-card

Full options#

type: custom:vacuum-card
device: Roborock Saros 20
title: Saros
image: auto
color: auto
show_logo: true
show_controls: true
room_selection: true
show_modes: true
show_routines: true
show_dock: true
show_consumables: true
show_stats: true
show_map: cleaning
map_entity: camera.dustbusters_map
collapsed:
  - stats
  - dock
crop:
  top: 170
  bottom: 190
  left: 180
  right: 150
language: fr

type: custom:vacuum-mini-card
device: Roborock F25 Ultra
title: F25
image: auto
color: dark
show_logo: true
show_controls: true
room_selection: true
zoom: true
language: fr

Options reference#

Cropping the map#

Map images often have wide empty borders. Remove them with crop, in pixels of the original image (all four values are optional):

type: custom:vacuum-card
crop:
  top: 170
  bottom: 190
  left: 180
  right: 150

In the visual editor, the values are under Map crop (pixels).

Click the map to open it full screen; click anywhere or press Escape to close it.

How it works

The cards read the Home Assistant entity and device registries instead of entity ids: every entity of a supported integration is matched by its translation_key (status, current_room, main_brush_time_left…) and by the device it belongs to. The keys of Xiaomi Miio, Dreame Vacuum, Ecovacs and iRobot are mapped onto the Roborock ones, so the same card reads all of them. Entity ids can therefore be in any language or renamed without breaking the cards.

States and errors are shown with the card's own translations when available, otherwise with Home Assistant's translation of the integration.

Brands#

The brand comes from the model id of the device: roborock.* → Roborock, the Mi / Xiaomi / Mijia robots (rockrobo.vacuum.v1, roborock.vacuum.m1s, xiaomi.*, mijia.*, ijai.* and the Mi models built by Dreame or Viomi) → Xiaomi, other dreame.* → Dreame, DEEBOT … → Ecovacs, Dyson product types (N223, 276, 277) → Dyson, iRobot SKUs (R980020, i755020, j755840, m611020…) → iRobot. A model of another brand gets the brand of its integration: Mi Home for Xiaomi Miio, Xiaomi for Xiaomi Home, Dreame for Dreame Vacuum, Ecovacs for Ecovacs, Dyson for Dyson, iRobot for iRobot. A Q5 Pro set up with Xiaomi Miio therefore shows the Roborock logo, an X10+ (built by Dreame, sold by Xiaomi) the Xiaomi one.

The brand gives the logo and the color of the buttons, taken from the logo, with a darker shade in the light theme so that they stay readable on a white card:

Brand	Light theme	Dark theme
Roborock	#ea0029	#ea0029
Xiaomi	#c24c00	#ff6900
Mi Home	#2a7f57	#43b17e
Dreame	#8a6a3c	#c9a46e
Ecovacs	#0b6bc4	#3d9be9
Dyson	#4a4a4a	#b8b8b8
iRobot	#4a8209	#64a70b

The Ecovacs and Dyson logos are drawn on a white rounded tile, so that they stay visible on a dark card; the iRobot logo is its green rounded tile.

Device pictures#

The picture is drawn from the device name and the commercial name of its model id (roborock.vacuum.a72 → Q5 Pro…), for about 130 models compatible with the integrations: Roborock E2 / S4 to S8, Q5 to Q10, the Qrevo range (Edge, Curv 2, S Pro…), Saros 10 / 20, G10 / G30, Dyad and F25; Xiaomi / Mijia Mi Robot Vacuum, 1S, Vacuum-Mop Essential / 1C / P / 2 / 2 Pro+ / 2 Ultra, X10 / X10+ / X20+, S10+, Omni 2, M40…; Dreame F9, D9, Z10 Pro, L10 Pro, D10 Plus, L10s Ultra; Ecovacs DEEBOT N8, OZMO, T8 to T30, X1 / X2 / X5 (Omni, Turbo); Dyson 360 Eye, 360 Heurist, 360 Vis Nav; iRobot Roomba 600 / 900, e5, i3 / i5 / i7, s9, j7 / j9, Combo j7+ / j9+ (with or without Clean Base) and Braava jet m6 — from their SKU, whatever the region (…020 Europe, …840 America…). A renamed device keeps the right picture. The full list is in Recognized models.

Saros robots, the E / C1 series and the Mi Vacuum-Mop Essential / 1C have no LiDAR turret; the Q series (Q5…Q10, Qrevo), the Xiaomi, Dreame and Ecovacs robots are white, the other robots (S series…) are dark; the dock is drawn when the integration reports one or the name implies it (Ultra, Plus / +, Qrevo, Saros, Omni, Self-Cleaning, G10 / G30). Wet-dry vacuums (roborock.wdv.*, roborock.wetdryvac.*) show an upright vacuum, dark for the Dyad series. iRobot robots have their own drawing: Roombas dark (the s9 D-shaped, the j series with its front camera) and in front of their Clean Base for the "+" models, the Braava jet white.

The picture is animated by the current activity, from the status, the cleaning mode and the dock drying: vacuuming (side brushes and dust), mopping (wet trail and drops), both, returning to the dock, washing the mops (bubbles) and drying them (heat waves), emptying the bin into an iRobot Clean Base (dust rising up the base); it stays still otherwise and with the reduced-motion setting. Use the image option to pick another model or your own picture, and color (white / dark) when your model exists in both colors.

Room selection#

The Start button opens a list of rooms to clean (or Whole home) when the integration can clean rooms (segments):

The segment ids of a Xiaomi Miio robot can be read with Xiaomi Cloud Map Extractor (rooms attribute of its camera) or found by trying xiaomi_miio.vacuum_clean_segment from the developer tools:

type: custom:vacuum-card
device: Living room robot
rooms:
  - id: 16
    name: Kitchen
  - id: 17
    name: Living room
  - id: 18
    name: Bedroom

The option can be set on the mini card too. It is YAML only (the visual editor keeps it).

Integrations#

• Roborock: the dock entities, which the integration puts on a separate "… Dock" device, are attached to their robot. The room selector reads the rooms of the current map (the one chosen in the integration's Selected map select) with the roborock.get_maps service, then cleans the selected rooms with the same app_segment_clean command the integration uses; when the robot is paused, the Start button resumes the cleaning instead. Routines created in the Roborock app appear as buttons in the integration; the card lists them and asks for confirmation before running one.
• Xiaomi Miio: current / last clean (clean_time, clean_area), totals (total_duration, total_area, count), last clean start / end, maintenance (main_brush_left, side_brush_left, filter_left, sensor_dirty_left) with their Reset buttons. The status comes from the vacuum entity, errors from its error attribute. Some of these sensors are disabled by default in the integration (totals, DND): enable them to see the statistics. No map: set map_entity to the camera of Xiaomi Cloud Map Extractor.
• Xiaomi Home: its entities have no translation_key, so the cards show the vacuum (status, fan speed, controls) and the battery only. No map: use map_entity as for Xiaomi Miio.
• Dreame Vacuum: status, battery, current room, cleaning progress, error, current and total cleaning, maintenance (main_brush_time_left, side_brush_time_left, filter_time_left, sensor_dirty_time_left, mop_pad_time_left) with the Reset buttons of the integration, and its map camera.
• Ecovacs: current and total cleaning (stats_area, stats_time, total_stats_*), cleaning mode (work_mode) and water amount (water_amount), maintenance in percent (lifespan_brush, lifespan_side_brush, lifespan_filter, lifespan_round_mop) with the reset_lifespan_* buttons, error code (0: no error) with its description, the station state (station_state: mops washed / dried, animated on the picture), and the map image. The error sensor is disabled by default in the integration: enable it to see the errors.
• Dyson (dyson_local): the vacuum entity only — status, power mode, controls — and the battery from its battery_level attribute. The picture is a dedicated Dyson 360 drawing.
• iRobot (roomba): the vacuum (status, fan speed — Automatic / Eco / Performance on the Roombas with Carpet Boost — or mopping behavior of the Braava, controls), the battery sensor, the current clean (time and area, attributes of the vacuum while it cleans; the area in m², or ft² with the US customary unit system), the error (error attribute) and the Bin full sensor as alerts, the statistics (total_missions, total_cleaned_area, total_cleaning_time, last_mission), the robot's water tank (tank_level, Braava and Combo) and the Clean Base's (dock_tank_level, Combo j9+). The vacuum's status attribute tells the Clean Base emptying the bin (Emptying Bin, shown and animated) and the robot charging. No map and no maintenance counters (the integration has none).
• Xiaomi Home, Ecovacs, Dyson and iRobot have no room cleaning the cards know: the Start button starts a full cleaning (no room selector). Only Roborock has the routine and dock sections.

Each maintenance line has a reset button when the integration exposes the matching reset button, and asks for confirmation before resetting the counter. The remaining time turns orange under 10 % of the part lifetime (or under 10 h when the lifetime is unknown), and red when it reaches 0; a percentage (Ecovacs, Roborock wet-dry vacuums) turns orange under 10 % and red at 0 %. Bars use the robot lifetimes: main brush 300 h, side brush 200 h, filter 150 h, sensors 30 h.

Recognized models#

Models the cards recognize from the model id the integration reports (drawn picture, logo and buttons of their brand). Any of these model ids can also be set as the image option to draw that model; the visual editor lists them by brand and name. iRobot SKUs of other regions are recognized all the same.

Support

If you find this project useful, you can support its development:

Features

• show_title and show_subtitle options (also in the visual editor) hide the header's title and its subtitle, separately, for a card placed under a section heading of its own (asked in juju35/ha-vehicle-card#72).

Features

• The header icon takes the color of the device state, on the full and the mini card: red on an error, offline, an empty clean water tank, a full dirty water tank, an empty cleaning fluid tank or a worn-out consumable; orange when paused, a water tank is low (25 % or less) or a consumable is nearly due; otherwise the color of the status (blue while cleaning, green docked or charging, grey idle). It keeps the brand color when the device reports no status.

Fixes

• Translations: the cards are defined once the page's language file has arrived (at most 1.5 s; Home Assistant builds a card when its element gets defined), so the first render is already translated instead of English then redrawn; until a language file is in, a missing text reads the English one wherever the card has no fallback of its own.

Performance

• Translations load on demand: the bundle keeps English only (296 KB → 192 KB) and each other language is its own vacuum-card.i18n.<lang>.js file next to it, fetched the first time a card needs it. Home Assistant loads every dashboard resource on every dashboard, so each page used to download and parse all 22 languages to use one. Until a language file has arrived (a few milliseconds), texts fall back to English, and the cards redraw once it is there.

Maintenance

• Build: scripts/i18n-split.mjs splits the built bundle and rebuilds every table from the split files to check them (the build fails on any difference); src/ keeps every language as before.
• Release: every file of dist/ is attached. Manual installation copies the translation files too.

Features

• iRobot: Roomba 976 (r976020) recognized and offered as an image preset; the 974 and 976 are drawn with their silver faceplate (picture added to the README gallery).

Fixes

• Mini card: the 40 px robot type icon keeps its size in the narrowest compact view (it shrank to 28 px below 200 px); the name gives way instead.
• "Last clean … ago" no longer freezes: the card re-checks it every minute while it is on the page.