Open-source project
piitaya/lovelace-mushroom avatar
piitaya/lovelace-mushroom

lovelace-mushroom: eighteen cards, zero required companions, and a licence named twice differently

Build a beautiful Home Assistant dashboard easily

5,279 stars448 forksTypeScriptApache-2.0

At a glance

What is it?
A set of Home Assistant dashboard cards whose selling point is that you never have to edit YAML or install another card, and whose manifest declares twelve runtime dependencies and a different licence from the one recorded for the repository. Contributors develop against the beta image of Home Assistant, the dev server is a real build served by preview, and one card is retired but still shipped.
Who is it for?
Mushroom is a sensible default for a Home Assistant dashboard when you want the standard look without hand writing configuration, because the editor covers all cards and all options, the colours come from the Material UI palette, and nothing else has to be installed. Two things to check.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 10 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • piitaya/lovelace-mushroom5,279 ★ · +102
Star history
Repository2026-09-232026-11-21
piitaya/lovelace-mushroom5.2k5.3k

102 Stars in the last 59 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The licence is named twice, and the two names are different

There is a licence file at the root of the repository, and there are two places that name a licence, and they do not agree with each other.

The licence recorded for the repository is Apache-2.0. The package manifest declares ISC in its own licence field, in the same file that gives the package its name and version. So a reader who checks the repository metadata and a reader who reads the manifest get different answers, and neither of them is the file at the root.

The practical advice is short: if you are about to redistribute this code, read the LICENSE file and work out from that which of the two manifest entries is the stale one. For an end user who installed the cards through a store, the question is probably moot, and for anyone vendoring the source it is not.

Zero dependencies means zero other cards, not zero packages

One feature line says zero dependencies, with the clarification that you need not install another card. Read in context that is accurate and important: Mushroom is a self-contained drop-in, and you are not being asked to assemble a set of Lovelace plugins to get a working dashboard.

Read as a statement about the package it is not accurate, and the manifest settles it. Twelve runtime dependencies are declared, including a web components library, a websocket client for Home Assistant, an internationalisation formatter, a YAML parser, a colour library, a gesture library, a sortable library, a validation library, an object hashing library and an icon path package.

That is an entirely normal set for a card collection and it explains the build step: those packages are bundled into the single mushroom.js file you install.

So the claim is about the Home Assistant ecosystem rather than about npm, and the two are not in conflict once you know which question each answers. It is still the kind of line that makes a reader check the manifest, which is a reasonable outcome.

Contributors develop against the beta image of Home Assistant

The development section tells you to run one command for a demo instance, and that command starts a container:

json
    "start:hass-stable": "docker run --rm -p8123:8123 -v ./.hass_dev:/config homeassistant/home-assistant:stable",
    "start:hass": "docker run --rm -p8123:8123 -v ./.hass_dev:/config homeassistant/home-assistant:beta",
    "start:hass-dev": "docker run --rm -p8123:8123 -v ./.hass_dev:/config homeassistant/home-assistant:dev"

Three tags are available and the one the readme documents, the plain start:hass, is the beta image. So the documented development environment is a moving target rather than a fixed one.

That choice is legible in the troubleshooting section, whose first step for a user who cannot see the latest changes is to check that their Home Assistant version is the latest, with the note that some new Mushroom features are only visible on the latest Home Assistant version. Whatever works against beta today can stop working against stable, and the cache clearing routine further down, deleting the Mushroom resource and reinstalling it from the store, is the user facing version of that same problem.

The dev server is a real build served by preview

The second half of the development instructions says to open another terminal, install dependencies, run the start script, and expect the server on port 4000. What that script actually does is worth reading, because it is not a hot reloading dev server:

json
    "start": "concurrently --kill-others --names build,serve \"vite build --watch\" \"vite preview\"",
    "build": "vite build",

So the loop is a watched production build with a preview server in front of it. Two consequences. You are testing the artefact that users get, bundles and minification included, rather than unbundled modules. And a change that compiles but breaks at runtime will show up here, which is the point of the arrangement.

The kill-others flag is the other detail. If either half exits, the other is taken down with it, so a build error stops the preview rather than leaving it serving a stale bundle.

The release build is the same tool without the watch, and it writes the single mushroom.js file that the manual installation instructions tell you to copy into your www folder. The manifest declares Vite ^8.0.11, TypeScript ^6.0.3 and ESLint ^10.3.0.

The project declines deep customization, and names what to use instead

There is a short paragraph in the features section that does more to set expectations than any feature list, and it is a refusal. The goal of Mushroom is not to provide a custom card for deep customization, and for that the readme points at two other projects, one for minimal user interface Lovelace configuration and one for a button card.

That is a scope decision, and a useful one. A dashboard that is easy to configure by clicking is necessarily a dashboard where the last five percent of layout control is somewhere else. Saying so up front is better than discovering it.

The same pattern appears in the troubleshooting section, which has a heading for card mod configuration and answers it with a sentence: help about card mod configuration is not provided in this repository, with a link to an issue tracking the state of card mod support. So the answer to whether card mods work is that it is an open question tracked in an issue, not a documented feature and not a documented refusal.

The design credit points the same way. The visual design is attributed to a named Behance work and to the minimal user interface Lovelace project, which is where the aesthetic lineage is stated plainly.

Eighteen cards, one of them retired but still shipped

The card list is organised by what you are controlling, not by layout, which is the right shape for a set like this. There is an alarm control panel card, a chips card, a climate card, a cover card, an entity card, an empty card, a fan card, a humidifier card, a light card, a lock card, a media player card, a number card, a person card, a select card, a template card, a title card, an update card and a vacuum card.

Then there is a section for legacy cards, with one entry. The legacy template card is described as considered legacy, not available in the card picker, but still usable. So it is dead in the picker and alive in the file, which means a dashboard that used it keeps working while nobody can add it to a new one.

Badges are handled separately, with a single template badge, and that one carries a version gate: it is available if you are using at least Home Assistant 2024.8.

The badge's Home Assistant 2024.8 floor is worth checking before you build a dashboard around it.

Manual installation needs Advanced Mode before the Resources menu exists

There are two installation routes. The store route is four steps, from installing the store itself to clicking a download button. The manual route is the interesting one, because it has a dependency that is not obvious until you fail to find the menu.

You download the mushroom.js file from the latest release and put it in the config/www folder. Then you add a reference to it in the dashboard, and the readme gives two ways. The interface route walks through Settings, then Dashboards, then a more options icon, then Resources, then add resource, with the URL set and the resource type set to a JavaScript module. The YAML route adds two lines to the lovelace section:

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

The interface route carries a note that has probably cost more people an afternoon than anything else on the page: if you do not see the Resources menu, you need to enable Advanced Mode in your user profile.

That is a Home Assistant interface setting, not a Mushroom one, and it is the one piece of the installation that the instructions cannot do for you.

Adding a language is four manual steps, not a pull request

Translations are handled through a translation platform, so helping with a language starts in your browser rather than in a text editor. What the readme then describes is the maintainer side of that arrangement, and it is more manual than you would expect.

Step one is a format requirement: language tags have to follow BCP 47 to stay compatible with Home Assistant, with the IANA subtag registry linked as the list to check against and examples given. Step two is to create a file named after the language code, in the translations folder under the source directory. Step three is to import that file into a specific TypeScript file and add the language to a record inside it. Step four is to test it locally by choosing the language in your Home Assistant profile through the interface.

Step three is the one that scales badly. The set of available languages is a record in a source file, so every new language is a code change by a maintainer rather than a file drop by a translator.

That is a reasonable trade for a project of this size, and it does mean the translation badge on the front page is only half the story. A language that has been translated is not available until someone has also registered it in the source.

Editorial conclusion

Mushroom is a sensible default for a Home Assistant dashboard when you want the standard look without hand writing configuration, because the editor covers all cards and all options, the colours come from the Material UI palette, and nothing else has to be installed. Two things to check. The licence, which is the one decision this repository leaves ambiguous: the recorded repository licence and the licence declared in the package manifest do not match, so read the LICENSE file rather than assuming either. And your Home Assistant version, since some features are documented as visible only on the latest release and the template badge needs 2024.8 or newer. If you want a dashboard tuned to the last detail, Mushroom is explicitly not the tool, and the readme names two projects for that instead of trying to be them.

Frequently asked questions

What are the mushroom cards in Home Assistant?

They are a set of dashboard cards covering alarm control panel, chips, climate, cover, entity, empty, fan, humidifier, light, lock, media player, number, person, select, template, title, update and vacuum. There is also a legacy template card that is no longer in the card picker but still usable, and a template badge that needs Home Assistant 2024.8 or newer.

Do I need to install another Home Assistant card to use Mushroom?

No. The feature list states zero dependencies in the sense that you need not install another card. The package manifest does declare twelve runtime dependencies, which are bundled into the built mushroom.js file you install.

How do I install Mushroom without the community store?

Download mushroom.js from the latest release, put it in your config/www folder, then reference it from the dashboard. You can add it through the Resources interface, which requires Advanced Mode enabled in your user profile, or with two lines of YAML in the lovelace section.

Why do I not see the latest Mushroom changes in my dashboard?

The readme's own checklist is: confirm your Home Assistant version is the latest, since some features only show there, confirm HACS has the latest version, check the version in the browser console, then clear the cache by deleting the Mushroom resource, uninstalling from HACS and reinstalling.

Does Mushroom support card mod configuration?

The repository does not provide help for it. The readme states that help about card mod configuration is not provided there and points to an issue tracking the state of card mod support.

Official sources

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

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/piitaya-lovelace-mushroom.svg)](https://hysenlabs.com/projects/piitaya-lovelace-mushroom)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/piitaya-lovelace-mushroom.svg)](https://hysenlabs.com/projects/piitaya-lovelace-mushroom)

Was this useful?