# Bubble Card: a minimalist custom card set for Home Assistant

> One JavaScript module, eleven card layouts, and a store of more than a hundred community modules. The interesting engineering is in the install story and the release cadence, not the card list.

**Clooos/Bubble-Card** — Bubble Card is a minimalist and customizable card collection for Home Assistant, featuring modern pop-ups and an integrated Module Store with over 100 community-made modules.

- Repository: https://github.com/Clooos/Bubble-Card
- Stars: 4,631 · Forks: 191
- Language: JavaScript
- License: MIT
- Published: 2026-10-06 · Updated: 2026-10-06 · Language: en
- Canonical page: https://hysenlabs.com/projects/clooos-bubble-card

## A Lovelace custom card, not a standalone dashboard app

Bubble Card registers itself as a Lovelace custom card inside Home Assistant. It does not replace your dashboard, talk to a server, or ship a backend of its own. The project describes itself as a minimalist and customizable card collection for Home Assistant, featuring modern pop-ups and an integrated Module Store with over 100 community-made modules, and that framing is accurate. The deliverable is one JavaScript file you register as a resource, after which the cards appear in the normal Add card menu.

The codebase matches that shape. It is JavaScript under an MIT license, built with webpack and lit, with js-yaml as the only other runtime dependency. A package.json that is marked private and carries version 0.0.0 tells you that the version tracked for users is the GitHub release tag, not the package version. The repository tree is short: src/, dist/, i18n/, hacs.json, a jest config, a webpack config and DEVELOPERS.md. There is no plugin host and no server component to deploy.

The repository is not archived, the last push was 2026-09-18, and v3.4.0 shipped the same day. At 4,595 stars and 189 forks it is a well-known name in the Home Assistant custom card scene, with 35 issues open right now.

## Two install paths, and the version bump people forget

The README documents two routes and recommends HACS. The manual route is deliberately spelled out in ten numbered steps because it is the one people get wrong: download bubble-card.js from the dist folder, drop it into your config www directory, register /local/bubble-card.js?v=1 as a JavaScript Module resource, then refresh. If you want a localized editor outside English, you also download a matching bubble-card-<lang>.json file and place it next to the JavaScript file.

That last detail is easy to skim past. Without the JSON file the editor works but stays in English, which looks like a bug until you know what causes it. The other detail is the reason the manual path has a reputation for being fussy: after any update you have to edit the resource string and change ?v=1 to some higher number, because browsers cache aggressively. Both install paths end with the same fallback advice, clear your browser cache, and on mobile that means every device you use the dashboard on.

The HACS route removes the version bump entirely. You install HACS, search for Bubble Card, download it, and the update path runs through the Community Store. The minimum supported Home Assistant version is 2023.9.0, which is a floor rather than a target. Several recent features do assume a much newer frontend.

## One card_type value covers eleven layouts

Every Bubble Card instance is two required keys plus an optional one. The type is always custom:bubble-card, and card_type picks the layout from a fixed list of eleven values: button, calendar, climate, cover, empty-column, horizontal-buttons-stack, media-player, pop-up, select, separator and sub-buttons. That is the entire configuration surface at the top level.

The third key, styles, takes a list of CSS stylesheets rather than individual properties, which is the design decision that shapes everything else about the project. Customization happens through stylesheets and variables, not through a growing matrix of per-card settings. It keeps the schema small, and it moves the cost of a theme change to the CSS layer where people who write CSS expect to find it.

Configuration happens in the Home Assistant editor for everything, with the YAML reference living in the linked documentation rather than the README. The README's table of contents shows where the detail actually lives: entity suggestions, card layouts, conditions, tap, double-tap and hold actions, styling, templates, modules, localization. Only the first three configuration sections sit in the README itself, which makes it a map rather than a manual.

## Seven global CSS variables instead of a theming panel

The styling story is seven variables. --bubble-border-radius and --bubble-main-background-color cover the general shape, --bubble-secondary-background-color and --bubble-accent-color handle contrast and emphasis, --bubble-icon-border-radius and --bubble-icon-background-color style the icons, and --bubble-sub-button-border-radius finishes off the sub-button layout.

Seven is a small palette for a project that markets itself on customization, and it only works because the variables are global. Set them once and every supported element follows, which is exactly what you want on a dashboard meant to be viewed at arm's length on a wall tablet. It also means there is no supported way to make one card a different accent color than its neighbors without dropping into raw CSS, which is the tradeoff you are accepting when you take this route.

The topics list on the repository says the same thing from a different angle: minimalism, mobile-first, dashboard, pop-up. Mobile-first shows up as a stated value rather than an afterthought, and the pop-up card type is the feature the project is known for.

## The module store is what turns eleven cards into a platform

The real answer to what Bubble Card is sits in the Module Store. The eleven core card types cover entity-shaped things: a button, a media player, a cover, a climate entity, a calendar, a select, plus three layout primitives in empty-column, separator and horizontal-buttons-stack. The store fills in everything that is not a single entity, and the README puts the count at over 100 community-made modules.

Modules also show up in the technical story. The v3.3.0 release notes describe an entity picker that, since v3.2.3 and on Home Assistant 2026.6 and up, can suggest Bubble Cards, and v3.3.0 takes that further by choosing cards based on what an entity can actually do and pairing them with modules. So the module concept is wired into the editor's discovery path rather than being a bolt-on gallery, which is a meaningful difference between an ecosystem and a download folder.

The community around it is real and organized: a YouTube channel with walkthroughs, a dedicated Reddit subreddit at r/BubbleCard, a long-running thread on the Home Assistant Community Forum, and donation links through Buy Me a Beer, PayPal and Patreon. When a single-maintainer project accumulates that much surface, the documentation becomes load-bearing, and the README is candid that the real reference lives in the docs site.

## v3.3 and v3.4 tell you what the maintainer prioritizes

Two releases three weeks apart show the direction better than any roadmap. v3.3.0 on 2026-08-28 is described as the largest release by added lines of code the maintainer has ever shipped. Its headline is localization: the editor is localized in the 64 languages Home Assistant supports, with right-to-left support and translated documentation. The maintainer notes the translations were produced with AI help and asks for corrections, which is worth knowing if you speak one of the less common locales.

v3.4.0 on 2026-09-18 is a different kind of release. The notes describe going back through old issues since v3.0.0, fixing bugs and landing feature requests, with the open issue count reaching one of its lowest points in a long time. The second theme is adopting newer Home Assistant frontend approaches that replace earlier workarounds. The third is performance, spent deliberately on anything that could slow the cards down, aimed at dashboards with many modules and custom styles on older hardware.

So the sequencing reads as: broaden the surface first, then stabilize and speed it up. For anyone hesitating on an older release, v3.3.0 is where the maintainer says to start.

The development setup is plain enough to describe in full. Copy .env.example to .env, optionally point HA_PATH at your Home Assistant www folder, and the dev build lands there instead of a local ./www directory.

```bash
# Copy this file to .env and customize for your local setup.
# .env is gitignored and will never be committed.

# Optional: path to your Home Assistant www folder (SMB mount, rsync target, etc.)
# If not set, the dev build outputs to ./www locally.
# HA_PATH=/Volumes/config/www
```

Build and test are the two scripts worth knowing, both routed through jest with the module flag set so ES modules work:

```json
  "scripts": {
    "dist": "webpack",
    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
    "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch"
  },
```

## Conclusion

Bubble Card is worth installing if your Home Assistant dashboard has outgrown the stock Lovelace cards and you want pop-ups that behave like the rest of the interface instead of a modal bolted on top of it. The module store is the part that keeps people on it, since 100-plus community modules cover a lot of ground the eleven core card types never will. The costs are real and worth naming before you start: a manual install hands you a cache-busting chore that HACS removes, the minimum supported Home Assistant version is 2023.9.0, and every visual adjustment runs through seven global CSS variables rather than per-card options. Check which install path you will actually maintain, because that version-number bump is the step people forget.

## FAQ

### What is a bubble card?

In general usage the phrase describes a small card-shaped element with a rounded or pill-like outline, the kind of thing you see in a mobile app layout. In the Home Assistant context that Google often matches instead, Bubble Card is a specific project: a minimalist custom card collection for Home Assistant that provides modern pop-ups, eleven built-in card layouts and a Module Store with over 100 community-made modules. The project is JavaScript, MIT licensed, and installs as one resource file or through HACS.

### What is a Home Assistant bubble card?

It is a Lovelace custom card that you add to a Home Assistant dashboard through the standard Add card menu. You pick a layout with the card_type key, using values such as button, media-player, cover, climate, calendar, select, pop-up, separator, empty-column, horizontal-buttons-stack or sub-buttons. Styling is applied through a list of CSS stylesheets and a set of seven global CSS variables, which makes theming consistent across every card on the view. The lowest supported Home Assistant version is 2023.9.0.

### How do I install and update Bubble Card in Home Assistant?

Use HACS if you can. Install and configure HACS, search for Bubble Card, download it, then add the card from your dashboard editor. Updates then arrive through the Community Store. The manual route puts bubble-card.js in your config www directory, adds a matching bubble-card-<lang>.json for a localized editor, and registers /local/bubble-card.js?v=1 as a JavaScript Module resource. On that route you must edit the resource and raise the number after every update or the browser keeps serving the old file, and the README's fallback for anything that looks broken is clearing the browser cache on each device you use.

## Sources

- [Clooos/Bubble-Card on GitHub](https://github.com/Clooos/Bubble-Card)
- [Issues](https://github.com/Clooos/Bubble-Card/issues)
- [License: MIT](https://github.com/Clooos/Bubble-Card/blob/main/LICENSE)
- [README](https://github.com/Clooos/Bubble-Card/blob/main/README.md)
- [Releases](https://github.com/Clooos/Bubble-Card/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/clooos-bubble-card