A frosted-glass theme for Home Assistant with first-class Bubble Card integration. One theme covers light and dark mode.
Preview rendered from the theme's own tokens, dark mode above and light mode below.
- What you get
- What you need
- Quick start
- Step-by-step setup
- Check that everything works
- Customizing
- Troubleshooting
- Upgrading from v1.x
- How it works
- Compatibility
- Uninstalling
- License
- Frosted glass surfaces. Each surface has a translucent tint, backdrop blur, a soft sheen, and a rim light. The rim light is a thin gradient edge, bright at the top-left like light catching real glass. Layered shadows add depth.
- No header bar. The dashboard title and tabs float on the background. A faint veil appears only while content scrolls underneath.
- Aurora background. Soft color glows sit behind the glass, and a fine grain stops gradient banding. The background stays put while cards scroll. It needs no network images, so it works offline.
- One accent color everywhere. A refined azure scale drives current Home Assistant buttons, switches, links, sliders, and focus rings. Button text stays readable in both modes.
- Light and dark mode in one theme. It follows your device, or you can pin a mode.
- Bubble Card styling through Bubble Card's own theme variables. An optional module adds blur, sheen, rim light, and glass footer buttons.
- Readable everywhere. Menus, pickers, and dropdown lists are solid. State colors (lights, climate, locks, alarms) are tuned separately for each mode.
- Mobile and accessibility aware. Phones get lighter blur. Surfaces turn solid when the OS asks for reduced transparency.
| Component | Needed? | What it adds |
|---|---|---|
| Home Assistant (current release) | Required | Colors, background, header and dialog blur, Bubble Card colors |
| HACS | Recommended | One-click install and updates |
| card-mod (4.x recommended) | Recommended | Blur, sheen, and rim light on standard Home Assistant cards; lighter phone blur; reduced-transparency fallback |
| Bubble Card 3.2+ | For Bubble dashboards | Bubble Card rows, pop-ups, and footer |
| Bubble Card Tools | For the module | Stores Bubble Card modules; needed for the Module Editor and import |
Without card-mod or the module, the theme still sets every color, edge, and shadow, plus the background, header blur, and dialog blur. You give up the blur, sheen, and rim light on cards and Bubble rows.
If you already have HACS, card-mod, and Bubble Card:
- Add
themes: !include_dir_merge_named themesunderfrontend:inconfiguration.yaml, then restart Home Assistant. - In HACS → ⋮ → Custom repositories, add
https://github.com/benkl/bubble-glasswith type Theme, then download Bubble Glass. - Run the
frontend.reload_themesaction, then pick Bubble Glass in your profile. - Import
examples/bubble-glass-module.yamlin any Bubble Card editor: Modules → My Modules → Import Module. - Reload the page.
Each step is explained below.
Home Assistant only loads theme files if configuration.yaml tells it where they are. Open configuration.yaml, using the File editor or Studio Code Server add-on, or Samba or SSH. Make sure it contains:
frontend:
themes: !include_dir_merge_named themes- If you already have a
frontend:block, add thethemes:line to it. Don't create a secondfrontend:block. - If you already have
themes: !include_dir_merge_named themes, skip this step. Bubble Glass sits next to your other themes. - If the
themesfolder doesn't exist in/config/, create it.
Restart Home Assistant (Settings → System → power icon in the top right → Restart Home Assistant). Reloading themes is not enough the first time.
- Open HACS, then ⋮ → Custom repositories. Or click the Open in HACS badge at the top of this page.
- Repository:
https://github.com/benkl/bubble-glass. Type: Theme. Click Add. - Search for Bubble Glass in HACS, open it, and click Download.
HACS puts the file under /config/themes/ and tells you when updates are available.
- Download
themes/bubble-glass.yaml. - Copy it into
/config/themes/.
You'll need to repeat this for updates.
- Go to Developer tools → Actions, run
frontend.reload_themes, and wait for the green check. - Click your user name at the bottom of the sidebar to open your Profile.
- Under Theme, choose Bubble Glass. Then pick Auto to follow your device, or force Light or Dark.
The theme choice is saved per user and per browser or device. To make Bubble Glass the default for everyone, including wall tablets with no logged-in profile, use the frontend.set_theme action. To have it set on every start, use an automation:
automation:
- alias: "Default theme: Bubble Glass"
triggers:
- trigger: homeassistant
event: start
actions:
- action: frontend.set_theme
data:
name: Bubble Glass # default (light) theme
- action: frontend.set_theme
data:
name: Bubble Glass
mode: dark # default dark themeTo use the theme on a single dashboard view only, set it on that view (Edit dashboard → view settings → Theme):
views:
- title: Home
theme: Bubble Glasscard-mod adds the parts a plain theme can't: blur, sheen, and rim light on standard cards, the lighter phone blur, and the reduced-transparency fallback.
-
In HACS, search for card-mod and click Download. HACS adds the dashboard resource for you.
-
Recommended: also load card-mod as a frontend module. Theme rules then apply faster, and the sidebar is styled on every page, not only on dashboards. Find the exact URL HACS created under Settings → Dashboards → ⋮ → Resources. It looks like
/hacsfiles/lovelace-card-mod/card-mod.js?hacstag=…. Add it toconfiguration.yaml:frontend: themes: !include_dir_merge_named themes extra_module_url: - /hacsfiles/lovelace-card-mod/card-mod.js?hacstag=12345678901 # use your own URL
Restart Home Assistant. Keep the HACS resource as well; Cast devices need it. When HACS updates card-mod, update the URL here too, so the file doesn't load twice.
-
Reload the browser page.
Skip this step if you only want the theme for standard Home Assistant cards.
- In HACS, search for Bubble Card and click Download.
- Reload the browser page. Bubble Card now appears in the card picker.
Bubble Card picks up Bubble Glass automatically through its theme variables. Nothing else is needed for colors, edges, and shadows.
The Bubble Glass module adds blur, sheen, and rim light to Bubble rows, edges to icon and sub-button chips, glass pop-up close buttons, and footer buttons that match the rows. It is a global module (is_global: true), so it applies to every Bubble Card at once.
Modules are stored by the Bubble Card Tools integration. Install it first if you haven't:
- In HACS, search for Bubble Card Tools (an Integration) and click Download.
- Restart Home Assistant.
- Go to Settings → Devices & services → Add integration, search Bubble Card Tools, and add it. It creates
/config/bubble_card/modules/.
Then install the module one of these ways:
- Import (easiest): open any Bubble Card in the dashboard editor and expand Modules. In My Modules, choose Import Module and paste the whole contents of
bubble-glass-module.yaml. - File copy: save the file as
/config/bubble_card/modules/bubble_glass.yamland reload the page. - Legacy (no Bubble Card Tools): merge the file's contents into
/config/bubble-modules.yamland restart Home Assistant.
Check that Bubble Glass shows All cards enabled in My Modules. HACS doesn't update modules, so after a theme update, re-import the module to get its latest version.
To leave one card out of the module, add this to that card's YAML:
modules:
- "!bubble_glass"examples/bubble-card-dashboard.yaml is a complete example: Bubble rows, climate and media cards, a separator, a pop-up, and a footer. To try it, create a new dashboard (Settings → Dashboards → Add dashboard), open it, and choose ⋮ → Edit dashboard → ⋮ → Raw configuration editor. Paste the example, then change the entity IDs to your own.
Settings that look best with this theme:
| Card | Setting | Value | Why |
|---|---|---|---|
| Pop-up | bg_opacity |
70–80 |
Translucent sheet that still reads clearly |
| Pop-up | bg_blur |
20–28 |
Frosted sheet over the dashboard |
| Pop-up | shadow_opacity |
25–35 |
Lifts the sheet off the page |
| Pop-up | backdrop_blur |
leave unset | Blurring the whole page and the sheet costs twice the GPU work |
| Horizontal buttons stack | highlight_current_view |
true |
The current page's button gets the accent color |
| Any card | use_accent_color |
true |
Uses the theme accent instead of the entity color |
| Look for | If it's missing |
|---|---|
| Dashboard background has soft color glows, not flat gray | Theme isn't active, or the view has its own background:. See Troubleshooting. |
| Standard cards (tile, entities, graphs) blur what's behind them and have a bright top-left edge | card-mod isn't loaded |
| Bubble rows blur, have a sheen, and a bright top-left edge | Module isn't installed or isn't set to All cards |
| Primary buttons are azure with readable text | An older theme is still selected in your profile |
| Dropdown menus are solid | Normal. Only cards are glass. |
To check the theme from the browser console (F12 → Console):
getComputedStyle(document.documentElement).getPropertyValue("--glass-surface")
// → "rgba(20, 25, 44, 0.46)" in dark mode, "rgba(255, 255, 255, 0.46)" in light modeAn empty result means Bubble Glass isn't the active theme on this page.
Don't edit the HACS-managed file; updates overwrite it. Make a copy instead:
- Copy
bubble-glass.yamlto/config/themes/bubble-glass-custom.yaml. - Rename the top-level key
Bubble Glass:toBubble Glass Custom:. - Change
card-mod-theme: "Bubble Glass"tocard-mod-theme: "Bubble Glass Custom". It must match the theme name, or card-mod rules stop applying. - Run
frontend.reload_themesand select Bubble Glass Custom.
Every surface is built from a few glass-* tokens, defined once per mode:
| Token | Used for |
|---|---|
glass-surface |
Cards, Bubble rows, footer buttons |
glass-surface-solid |
Menus, pickers, dropdown lists; also the reduced-transparency fallback |
glass-surface-raised |
Dialogs and bottom sheets |
glass-surface-float |
Footer buttons that float over content |
glass-chip / glass-chip-active |
Icon and sub-button chips; selected list item |
glass-on-accent / glass-on-text-shadow |
Text and icon color on accent-filled buttons; text shadow on active rows |
glass-border-color |
One-pixel base edge |
glass-rim |
Rim-light gradient drawn over the edge |
glass-sheen |
Light falloff across a surface |
glass-shadow / glass-shadow-row / glass-shadow-float |
Depth of cards, Bubble rows, and the floating footer |
glass-backdrop-filter |
Blur recipe (top level, shared by both modes) |
glass-header-scrolled |
Veil behind the dashboard header while scrolled (card-mod) |
More or less frosting. Change the top-level blur:
glass-backdrop-filter: "blur(30px) saturate(180%)" # heavier
glass-backdrop-filter: "blur(12px) saturate(140%)" # lighterMore solid cards for busy backgrounds. Raise the alpha (the last number) of glass-surface in each mode, for example rgba(20, 25, 44, 0.65) in dark mode.
Your own background image. Put the image in /config/www/backgrounds/ and replace lovelace-background in both modes:
lovelace-background: "center / cover no-repeat url('/local/backgrounds/home.jpg') fixed"Keep the word fixed: it tells Home Assistant to pin the background while the cards scroll. To set a background for a single view, use the view's Background setting instead.
Bring back a header bar. Give the header a tint in each mode, for example:
app-header-background-color: "rgba(7, 11, 23, 0.55)" # dark
app-header-background-color: "rgba(245, 248, 254, 0.62)" # light
app-header-border-bottom: "1px solid var(--divider-color)"To remove even the scroll veil, set glass-header-scrolled: "transparent".
No grain. Delete the first layer of lovelace-background: the url("data:image/svg+xml,…") entry and the comma after it.
Different accent color. Set primary-color and accent-color in each mode. Then replace the eleven ha-color-primary-05 … ha-color-primary-95 steps at the top of the file with a scale in your hue, running from darkest (05) to lightest (95). Home Assistant fills primary buttons with step 40 and puts white text on them, so keep step 40 dark enough for at least 4.5:1 contrast with white. Set text-primary-color to a color that contrasts with your primary-color.
Fast flat mode for slow wall tablets:
glass-backdrop-filter: "none"
# and in each mode:
glass-surface: "rgba(20, 25, 44, 0.85)" # dark
glass-surface: "rgba(255, 255, 255, 0.85)" # lightBubble Glass doesn't appear in the theme list.
Check that themes: !include_dir_merge_named themes is under frontend: and that you restarted after adding it. A YAML error in any file in the themes folder can stop all themes from loading. Check Settings → System → Logs for themes errors, then run frontend.reload_themes.
The theme is selected, but the dashboard background is flat.
The view or dashboard has its own background (view settings → Background, or background: in YAML), which overrides the theme. Remove it. Settings pages always use the plain page color; only dashboards show the aurora.
Standard cards aren't blurred and have no bright edge.
card-mod isn't loaded. Check Settings → Dashboards → ⋮ → Resources for card-mod.js, then hard-reload the page (Ctrl/Cmd + Shift + R). If one card has its own card_mod: style that sets background or backdrop-filter, it overrides the theme on that card.
Bubble rows look flat, with no sheen, blur, or rim. The module isn't active. Open Modules → My Modules in any Bubble Card editor and check that Bubble Glass is installed with All cards on. If the editor warns about storage, set up Bubble Card Tools (step 6).
The Bubble Card footer moved into the page, scrolls away, or a dropdown opens in the wrong place.
Something gave a Bubble Card a backdrop-filter, filter, or transform. Any of these traps Bubble Card's fixed footer and menus inside the card. Common causes: a card_mod: style on the Bubble Card, another theme or module that sets --ha-card-backdrop-filter, or an old copy of a v1 module. Bubble Glass deliberately never filters Bubble Card's outer card.
The footer buttons have a double border.
Remove any old per-card styles: block from earlier Bubble Glass READMEs on your horizontal-buttons-stack. The module styles the footer now.
A transparent sub-button card or custom card got a frame or sheen.
Exclude it from the module on that card with modules: ["!bubble_glass"].
Active buttons are hard to read.
Accent-filled buttons use bubble-button-accent-color with white text. The white text and icon come from the module, so make sure module v2.1 or newer is installed. To change the fill, pick a color with at least 4.5:1 contrast against white. Light rows use the light's own color; Bubble Card darkens it for white text, and the module adds a text shadow in dark mode.
Content shows through the footer. Install module v2.1 or newer, and leave the footer's Hide gradient option off.
Text is hard to read over my own background image.
Raise the alpha of glass-surface (see Recipes), or use a darker or blurrier image.
Scrolling stutters on a wall tablet.
Backdrop blur is GPU work. Use the fast flat mode, or lower glass-backdrop-filter to blur(8px).
Changes don't show up after an update.
- Run
frontend.reload_themes. - Hard-reload the browser.
- In the iOS Companion app, go to Settings → Companion app → Debugging → Reset frontend cache. On Android, clear the app cache in the system app settings.
- Re-import the module; HACS doesn't update it.
The wrong mode shows.
Auto follows the device's light/dark setting. Pick Light or Dark in your profile to pin it. For devices with no profile, see frontend.set_theme with mode: in step 3.
- Update through HACS and run
frontend.reload_themes. - Re-import the module (Modules → My Modules): delete the old Bubble Glass entry, then import the new file.
- Remove the per-card footer
styles:block if you copied it from the v1 README. - If your own styles used Bubble Glass tokens, rename them:
| v1 token | v2 token |
|---|---|
glass-background |
glass-surface |
glass-background-strong |
glass-surface-raised |
glass-background-soft |
glass-chip |
glass-chip-background |
glass-chip |
glass-shadow (single shadow) |
glass-shadow (now includes highlights), glass-shadow-row, glass-shadow-float |
glass-highlight-color, glass-rim-color |
glass-rim (gradient) |
| Layer | Where | What it does |
|---|---|---|
| Theme variables | themes/bubble-glass.yaml |
Colors, accent scale, background, card tint, edges, shadows, header and dialog blur, Bubble Card variables |
| card-mod rules | card-mod-card, card-mod-root-yaml, card-mod-sidebar in the same file |
Blur, sheen, and rim light on standard cards; lighter blur on phones; reduced-transparency fallback; sidebar blur |
| Bubble Card module | examples/bubble-glass-module.yaml |
Blur, sheen, and rim light on Bubble rows and footer buttons; chip edges; pop-up buttons |
The rules respect two constraints:
- Never filter a Bubble Card's outer card.
backdrop-filtermakes an element the containing block for its fixed-position children, which would pull Bubble Card's footer and menus out of place. card-mod skipsbubble-card. The module blurs only the row's innermost background layer. - Leave Home Assistant's transparent cards alone. Heading, toggle-group, and transparent clock and date cards get no blur, so no stray frosted boxes appear.
docs/research-and-plan.md records the source-level findings behind each decision.
| Area | Status |
|---|---|
| Home Assistant | Current releases. The theme uses the ha-font-family-*, ha-color-primary-*, dialog, and header variables from the redesigned frontend. On older versions some variables are ignored, but nothing breaks. |
| Bubble Card | 3.2+ (pop-ups); checked against 3.4.3 |
| card-mod | 4.x recommended; checked against 4.2.1 |
| Chrome, Edge, Android WebView, Fully Kiosk | Full support |
| Safari / iOS Companion app | iOS/macOS 18+ for full blur. Older versions show the tinted glass without header blur. |
| Firefox | 103+ |
- Pick another theme in your profile. If you added a
frontend.set_themeautomation, remove it too. - Delete the module in Modules → My Modules.
- Remove the theme in HACS, or delete
/config/themes/bubble-glass.yaml. - Run
frontend.reload_themes.
Derived from the MIT-licensed Bubble theme by Clooos. Distributed under the MIT License.
