Mushroom cards for Home Assistant: a Lovelace card set you configure in the UI editor

What Mushroom solves on a Home Assistant dashboard

Home Assistant ships a default card set, and building a dashboard that looks coherent usually means writing YAML for each card, picking icons by hand and repeating the same options across dozens of entries. Mushroom is a collection of cards for the Home Assistant Dashboard UI, and its stated mission is to offer easy to use components for building that dashboard. The audience is the person who wants a presentable dashboard without maintaining a card library, not the person tuning every pixel.

The README lists the feature set plainly: an editor for all cards and all options so there is no need to edit yaml, an icon picker, a color picker, zero dependencies (no need to install another card), colors based on Material UI, light and dark theme support, optional theme customization and internationalization. Each of those is a decision about who the project is for. The icon and color pickers matter because choosing an icon is the most repeated chore in dashboard work. The zero dependency claim matters because a card that requires another card to be installed first is a support burden.

The project is explicit about its ceiling. The README states that the goal of Mushroom is not to provide custom cards for deep customization, and points to UI Lovelace Minimalist and Button card for that. That sentence is the honest boundary of the project, and it should shape whether you install it.

How the cards are structured and what runs in the browser

Mushroom is a TypeScript project built with Vite. The build output is a single mushroom.js file, and the package.json shows the runtime dependencies that end up in that bundle: lit for the web components, @mdi/js for icons, culori and color-name for color handling, hammerjs for gestures, sortablejs for drag behavior, js-yaml, superstruct for config validation, intl-messageformat for translations, home-assistant-js-websocket, memoize-one and object-hash. The build command is vite build, and the README says it produces mushroom.js in the dist folder.

Cards are grouped by entity type rather than by layout. The docs folder holds one page per card: alarm control panel, chips, climate, cover, entity, empty, fan, humidifier, light, lock, media player, number, person, select, template, title, update and vacuum. A legacy template card exists but is not offered in the card picker. There is also a template badge, which the README says is available if you are using at least Home Assistant 2024.8.

Because the bundle is loaded as a JavaScript module into the dashboard, the cards run in the browser alongside the Home Assistant frontend. That is why the troubleshooting section tells you to check the browser console for the Mushroom version and to clear cache when a change does not appear. There is no server side component to restart.

Installing Mushroom through HACS and adding your first card

The README gives two installation paths. HACS is the intended one: install HACS if it is not already present, open HACS in Home Assistant, search for "Mushroom", and click the download button. There is also a my.home-assistant.io redirect link that opens the repository directly inside HACS.

If you prefer to manage the file yourself, download mushroom.js from the latest release and place it in your config/www folder. Then register it as a resource in the dashboard. Through the UI the path is Settings, Dashboards, the More Options icon, Resources, Add Resource, with the Url set to /local/mushroom.js and the Resource type set to JavaScript Module. The README notes that if the Resources menu is missing you need to enable Advanced Mode in your User Profile.

In YAML the same resource is declared like this:

resources:
  - url: /local/mushroom.js
    type: module

Once the resource is registered, the README describes the usage flow: in the Dashboard UI click the three dots in the top right corner, click Edit Dashboard, click the Plus button to add a new card, then find one of the Custom: Mushroom cards in the list. Every card is then configured in the editor, which is the point of the project. If you want to run a local Home Assistant instance to try this against, package.json defines npm run start:hass, which starts the Home Assistant beta image with docker on port 8123, and npm run start:hass-stable for the stable image.

Where Mushroom stops: card-mod, deep customization and legacy cards

The clearest limitation is styling. The README's troubleshooting section says that help about card mod configuration is not provided in this repository and links to an issue about the state of card-mod support. If your dashboard plan depends on injecting CSS into cards, Mushroom is the wrong starting point, and the project says so rather than pretending otherwise. The same applies to layout: a card set organized around entity types gives you a light card, a climate card and a cover card, not a blank canvas for arbitrary compositions.

The legacy template card is a second edge. It still works, but the README states it is not available in the card picker, so anyone who built dashboards on it is configuring YAML by hand, which is exactly what the rest of the project tries to avoid. The template badge has a version floor as well: it requires at least Home Assistant 2024.8.

There is also a version coupling with Home Assistant itself. The troubleshooting steps begin by telling you to check that your Home Assistant version is the latest, because some new Mushroom features can only be visible for the latest Home Assistant version. Running an older Home Assistant core means some cards may behave differently than the current documentation describes, and the fix is to upgrade Home Assistant, not Mushroom.

Mushroom compared with UI Lovelace Minimalist and Button card

The README names the alternatives itself. UI Lovelace Minimalist and Button card are recommended for deep customization, and Mushroom's design is credited as inspired in part by UI Lovelace Minimalist and by 7ahang's work on Behance. The difference is in the approach to configuration. Mushroom ships one card per entity type with an editor for every option, so the card knows what a light or a vacuum is and presents the relevant controls. Button card takes the opposite route: you describe what the button should do, and the visual result is assembled from your configuration. Minimalist is a broader dashboard system rather than a card collection.

That distinction decides the choice. If your dashboard is mostly standard entities and you want it built in an afternoon through the UI, Mushroom's per-entity cards are less work. If you want a dashboard where the cards do not look like anyone else's, the two projects the README points at are the ones designed for that, and Mushroom's own documentation says as much. Neither approach is a superset of the other.

Themes, translations and the cost of keeping Mushroom current

Mushroom works without a theme, but the README recommends installing Mushroom Themes for a better experience and links to the Home Assistant documentation about themes for background. Theme customization is optional, so a theme is a separate thing you maintain and not a requirement for the cards to render.

Translations are handled through Weblate, and the README describes the maintainer steps for adding a language: language tags must follow BCP 47, a new file named with the language code goes into the translation folder in src/translations, and it must be imported into localize.ts and added to the languages record. Examples given are fr, fr-CA and zh-Hans. That is a maintainer workflow, not something a dashboard user touches.

Upgrade cost is low but not zero. Since the deliverable is one JavaScript module loaded into the dashboard, updating through HACS replaces the file, and the failure mode is a stale cached bundle rather than a broken install. The troubleshooting section addresses exactly this: check the Home Assistant version, check that you have the latest Mushroom version on HACS, check the version in the browser console, and if it still looks wrong, delete the mushroom resources, uninstall Mushroom from HACS and reinstall it. The repository is licensed Apache-2.0 according to its LICENSE file, while package.json declares ISC in its license field; if the licence matters to your distribution plans, read the LICENSE file itself rather than either metadata line.

What the Mushroom card list covers and what it leaves to template

The card list is the practical index of what Mushroom can do without YAML. There are dedicated cards for alarm control panels, climate, covers, fans, humidifiers, lights, locks, media players, numbers, persons, selects, updates and vacuums, plus chips, title and empty cards for structure. The entity card is the general purpose one, and the template card is the escape hatch when an entity type has no dedicated card.

The template card is where the project's ambition and its limits meet. It lets you express something the fixed cards do not cover, but doing so means writing template configuration, and the README's promise of an editor for all options is most valuable on the fixed cards. If most of your dashboard ends up on template cards, you have effectively chosen the customization path while staying inside a project that says it is not built for that, and the alternatives above become worth a look.

Chips deserve a separate mention because they are the compact row elements rather than full cards, and they are among the most searched parts of the project. The chips card documentation lives in docs/cards/chips.md alongside the rest.

Editorial conclusion

Adopt Mushroom if you want a consistent Home Assistant dashboard without writing card YAML, and if your entities map onto its card list: light, climate, cover, media, vacuum, lock, fan, humidifier, number, person, select, update, alarm, chips, title, template and empty. Skip it if your dashboard depends on card-mod styling or bespoke layouts; the README points elsewhere for that and states that card-mod help is not provided in the repository. Before installing, confirm your Home Assistant version is current, since the troubleshooting section notes that some Mushroom features only appear on the latest Home Assistant release, and check the browser console for the loaded Mushroom version if a card looks stale.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. piitaya/lovelace-mushroom on GitHub
4. README
5. Releases