Awesome

Bubble Card

Bubble Card is a minimalist and customizable card collection for Home Assistant with a nice pop-up touch.

Table of contents

Installation Configuration Pop-up Horizontal buttons stack Button Media player Cover Select Climate Separator Empty column Sub-buttons Card layouts Actions Styling Templates Conflicts Help Donate

Installation

Home Assistant lowest supported version: 2023.9.0

1. Download these files: bubble-card.js and bubble-pop-up-fix.js
2. Add these files to your <config>/www folder
3. On your dashboard click on the icon at the right top corner then on Edit dashboard
4. Click again on that icon and then click on Manage resources
5. Click on Add resource
6. Copy and paste this: /local/bubble-card.js?v=1
7. Click on JavaScript Module then Create
8. Go back and refresh your page
9. You can now click on Add card in the bottom right corner and search for Bubble Card
10. After any update of the file you will have to edit /local/bubble-card.js?v=1 and change the version to any higher number

If it's not working, just try to clear your browser cache.`

This method allows you to get updates directly on the HACS main page

1. If HACS is not installed yet, download it following the instructions on https://hacs.xyz/docs/setup/download/
2. Proceed to the HACS initial configuration following the instructions on https://hacs.xyz/docs/configuration/basic
3. On your sidebar go to HACS > Frontend
4. Click on the + button at the bottom right corner
5. Now search for Bubble Card and then click on the button at the bottom right corner to download it
6. Go back on your dashboard and click on the icon at the right top corner then on Edit dashboard
7. You can now click on Add card in the bottom right corner and search for Bubble Card

If it's not working, try to clear your browser cache.

Videos

You can also take a look at my YouTube channel for step by step videos.

Configuration

All options can be configured in the Home Assistant editor. But you can find more details and the YAML in the documentation below.

<summary>Main options (YAML + description)</summary>

Check out this video to learn about Bubble Card and its capabilities. My YouTube channel is quite new and focuses on tutorials about Home Assistant and Bubble Card. Don’t hesitate to subscribe to help increase my channel’s visibility. Thank you in advance!

Pop-up

This card allows you to convert any vertical stack into a pop-up. Each pop-up is hidden by default and can be opened by targeting its link (e.g. '#pop-up-name'), with any card that supports the navigate action, or with the horizontal buttons stack that is included.

[!IMPORTANT]
This card must be placed within a vertical stack card at the topmost position to function properly. To avoid misalignment with your view, place vertical stacks/pop-ups after all other dashboard cards. It should be called from the same view to work.

<details> <summary><b>How to create a pop-up in the editor</b></summary> <br>

1. To add a pop-up you first need to add a Vertical stack card to your dashboard.
2. This Vertical stack must be after all your other cards in your view order and before your horizontal buttons stack if you have one. In a section view type it can be placed anywhere.
3. Now add a Bubble Card with the Pop-up type.
4. Just fill in the Hash input and the ones you need.

You can also watch this step by step video.

</details>

[!TIP]

Pop-up trigger

This feature allows you to open a pop-up based on the state of any entity, for example, you can open a "Security" pop-up with a camera when a person is in front of your house. You can also create a toggle helper (input_boolean) and trigger its opening/closing in an automation.

<details> <summary>Opening a pop-up when a <code>binary_sensor</code> is <code>on</code></summary> <br>

type: custom:bubble-card
card_type: pop-up
hash: '#kitchen'
name: Security
icon: mdi:video
trigger_entity: binary_sensor.front_door_motion
trigger_state: 'on'
trigger_close: true

</details>

Different ways to close a pop-up

They are many ways to close a pop-up. For instance, you can swipe from the pop-up header to the bottom, by doing a long swipe inside the pop-up to the bottom, by pressing Escape on desktop, by removing the hash in the URL or by simply pressing the close button.

Pop-up initialization fix

If you notice that pop-up content appears upon page load, consider installing this fix as an additional module.

<details> <summary>Installation</summary> <br>

You can do this by adding bubble-pop-up-fix.js to your configuration.yaml like so:

frontend:
  extra_module_url:
    - /hacsfiles/Bubble-Card/bubble-pop-up-fix.js

If you didn't install it with HACS, change the path accordingly. Then, clear your browser cache.

For Android Home Assistant Companion App users, you can close the app, then clear the app cache. If it's still not working, you can close and restart the app again.

For iOS Home Assistant Companion App users, you can go to your Home Assistant settings, then navigate to Companion App > Debug > Clear Frontend Cache (or something similar), then refresh the page or restart the app.

For previous users of the Optimized mode, you will need to replace your type: custom:bubble-pop-up with this in YAML mode:

type: vertical-stack
cards:
  - type: custom:bubble-card
    card_type: pop-up

</details>

Pop-up options

<summary>Options (YAML + descriptions)</summary>

Examples

type: vertical-stack
cards:
  - type: custom:bubble-card
    card_type: pop-up
    hash: '#kitchen'
    name: Kitchen
    icon: mdi:fridge
    entity: light.kitchen

type: custom:bubble-card
card_type: button
button_type: name
name: Kitchen
icon: mdi:fridge
button_action:
  tap_action:
    action: navigate
    navigation_path: '#kitchen'

Replace 400px with the size you need.

type: vertical-stack
cards:
  - type: custom:bubble-card
    card_type: pop-up
    hash: '#kitchen'
    name: Kitchen
    icon: mdi:fridge
    entity: light.kitchen
    margin_top_mobile: calc(100vh - 400px)
    margin_top_desktop: calc(100vh - 400px)

Horizontal buttons stack

This card is a good companion to the pop-up card, allowing you to open the corresponding pop-ups. It also allows you to open any page of your dashboard. In addition, you can add your motion/occupancy sensors so that the order of the buttons adapts according to the room you just entered. This card is scrollable, remains visible, and acts as a footer.

[!IMPORTANT]
This card has to be the last one in your view (after every card and pop-up). It can't be inside any stack.

Horizontal buttons stack options

<summary>Options (YAML + descriptions)</summary>

[!IMPORTANT]
The variables starting with a number define your buttons, just change this number to add more buttons (see example below).

Example

type: custom:bubble-card
card_type: horizontal-buttons-stack
auto_order: true
1_name: Living room
1_icon: mdi:sofa
1_link: '#living-room'
1_entity: light.living_room
1_pir_sensor: binary_sensor.living_room_motion
2_name: Kitchen
2_icon: mdi:fridge
2_link: '#kitchen'
2_entity: light.kitchen
2_pir_sensor: binary_sensor.kitchen_motion
3_name: Dining room
3_icon: mdi:silverware-fork-knife
3_link: '#dining-room'
3_entity: light.dining_room
3_pir_sensor: binary_sensor.dining_room_motion

Button

This card allows you to control your entities and can be customized in many ways. To access color / control of an entity, simply tap on the icon.

[!TIP]

What are the differences between all the button types?

• The button switch is the default one. By default, it toggles an entity and its background color changes based on the entity’s state or the color of a light.

• The button slider can control the brightness of a light, the volume of a media player, the position of a cover, and it also supports input numbers. Its background color can change based on the color of a light.

• The button state is perfect for displaying information from a sensor or any entity. When you press it, it will show the "More info" panel of the entity. Its background color does not change.

• The button name is the only one that doesn't need an entity and allows you to display a short text, a name or a title. You can also add some actions to it. Its background color does not change.

Button options

<summary>Options (YAML + descriptions)</summary>

Examples

type: custom:bubble-card
card_type: button
button_type: slider
entity: light.kitchen_led
name: Kitchen LED
icon: mdi:led-strip-variant

entity: light.your_light
button_type: switch
show_icon: true
force_icon: true
show_name: true
show_last_changed: true
show_state: true
show_last_updated: true
show_attribute: true
attribute: brightness
scrolling_effect: true
card_layout: large
button_action:
  tap_action:
    action: toggle
tap_action:
  action: more-info
sub_button:
  - entity: light.your_light
    icon: ''
    show_state: false
    show_attribute: true
    attribute: brightness
    show_icon: false
    show_background: false
    show_name: false

Media player

This card allows you to control a media player. You can tap on the icon to get more control.

Media player options

<summary>Options (YAML + descriptions)</summary>

Hide options

Examples

type: custom:bubble-card
card_type: media-player
name: Media player
entity: media_player.your_media_player
show_state: true
show_last_updated: true
show_attribute: true
attribute: assumed_state
card_layout: large
scrolling_effect: false
show_icon: false
force_icon: true
show_name: false
show_last_changed: true
columns: 2
rows: 1
tap_action:
  action: toggle
hide:
  play_pause_button: true
  volume_button: true
  previous_button: true
  next_button: true
  power_button: true
sub_button:
  - entity: media_player.salon_2
    icon: mdi:volume-high
    name: Volume level
    tap_action:
      action: more-info
    show_name: false
    show_state: false
    show_last_updated: false
    show_attribute: true
    show_background: false
    attribute: volume_level

Cover

This card allows you to control your cover entities.

Cover options

<summary>Options (YAML + descriptions)</summary>

Example

type: custom:bubble-card
card_type: cover
entity: cover.kitchen
name: Kitchen
icon_open: mdi:roller-shade
icon_close: mdi:roller-shade-closed

Select

This card allows you to add a dropdown menu for your input_select / select entities. This card also supports the sub-buttons and all the common Bubble Card features.

[!TIP] You can also have select sub-buttons if you want, this feature is available in all the cards that support the sub-buttons.

Select options

<summary>Options (YAML + descriptions)</summary>

Examples

type: custom:bubble-card
card_type: select
name: Scene
entity: input_select.scenes
icon: mdi:brightness-4
show_state: true

Climate

This card allows you to control your climate entities.

[!TIP] The mode selection menu is a sub-button that is added automatically when creating the card. You can then modify or remove it as you wish.

Climate options

<summary>Options (YAML + descriptions)</summary>

Examples

type: custom:bubble-card
card_type: climate
entity: climate.test_climate
sub_button:
  - name: HVAC modes menu
    select_attribute: hvac_modes
    show_arrow: false
    state_background: false

Separator

This card is a simple separator for dividing your pop-up into categories / sections. e.g. Lights, Devices, Covers, Settings, Automations...

Separator options

<summary>Options (YAML + descriptions)</summary>

Example

type: custom:bubble-card
card_type: separator
name: Covers
icon: mdi:window-shutter

Empty column

This card is here to fill an empty column. This is useful if you have a horizontal-stack in your pop-up with only one card. Take a look at the bottom right corner of this screenshot to (not) see it.

Empty column options

This card has no options and doesn’t support styling, though it does support layout options for HA sections.

Example

type: horizontal-stack
cards:
  - type: custom:bubble-card
    card_type: button
    ...
  - type: custom:bubble-card
    card_type: empty-column

Sub-buttons

In every card that supports that option, you can add sub-buttons to customize your cards even more. You can, for exemple, create a button that can control a vacuum, a weather card, or almost anything that you can come up with. These sub-buttons support the tap actions and most of the button options.

Sub-buttons options

<summary>Options (YAML + description)</summary>

Examples

type: custom:bubble-card
card_type: button
button_type: switch
name: Vacuum
entity: vacuum.downstairs
icon: mdi:robot-vacuum
show_state: true
show_last_changed: true
tap_action:
  action: more-info
button_action:
  tap_action:
    action: more-info
sub_button:
  - name: Battery
    icon: mdi:battery
    show_name: false
    show_icon: true
    show_background: false
    show_attribute: true
    attribute: battery_level
  - name: Return to dock
    icon: mdi:home
    show_background: false
    tap_action:
      action: call-service
      service: vacuum.return_to_base
      target:
        entity_id: vacuum.downstairs
  - name: Pause
    icon: mdi:pause
    show_background: false
    tap_action:
      action: call-service
      service: vacuum.pause
      target:
        entity_id: vacuum.downstairs
  - name: Start
    icon: mdi:play
    tap_action:
      action: call-service
      service: vacuum.start
      target:
        entity_id: vacuum.downstairs
styles: >-
  .bubble-button-card-container {
    /* Change the background color when the vacuum get an error (optional), more details in the styles template section */
    background: ${state === 'error' ? 'rgb(200, 80, 40)' : ''} !important;
  }
  /* Change the first sub-button battery icon based on the battery_icon attribute, more details in the styles template section */
  ${subButtonIcon[0].setAttribute("icon", hass.states['vacuum.downstairs'].attributes.battery_icon)}

type: custom:bubble-card
card_type: button
button_type: slider
name: Kitchen
entity: light.kitchen
icon: mdi:fridge-outline
show_last_updated: true
sub_button:
  - name: Brightness
    icon: mdi:fridge-outline
    show_icon: false
    show_background: false
    show_attribute: true
    attribute: brightness
  - name: Toggle button
    icon: mdi:lightbulb
    tap_action:
      action: toggle

Bad luck for me it's cloudy all the time but all the icons are changing based on the weather.

type: custom:bubble-card
card_type: button
button_type: state
entity: weather.openweathermap
name: Weather
show_state: true
card_layout: large-2-rows
sub_button:
  - name: Home temperature
    icon: mdi:home-thermometer-outline
    entity: sensor.home_temperature
    show_state: true
    show_icon: true
    show_background: false
  - name: Outside temperature
    entity: sensor.outside_temperature
    show_state: true
    show_background: false
  - name: Today
    entity: sensor.home_realfeel_temperature_max_0d
    show_name: true
    show_state: true
    tap_action:
      action: more-info
  - name: Tomorrow
    entity: sensor.home_realfeel_temperature_max_1d
    show_name: true
    show_state: true
    show_background: false
styles: >-
  /* Change the third and fourth sub-button icon based on the forecast.condition attribute, more details in the styles template section */
  ${subButtonIcon[2].setAttribute("icon", getWeatherIcon(hass.states['sensor.weather_forecast_daily'].attributes.forecast[0]?.condition))}
  ${subButtonIcon[3].setAttribute("icon", getWeatherIcon(hass.states['sensor.weather_forecast_daily'].attributes.forecast[1]?.condition))}

Card layouts

Bubble Card fully supports the Home Assistant section view, you can change the card layout to make the card bigger and also change the number of columns or rows the card should occupy in your section view (only on the cards that support that option). These layouts are also supported in all other view types.

<summary>Available card layouts</summary>

Example

type: custom:bubble-card
card_type: button
button_type: state
card_layout: large-2-rows
name: Energy
entity: sensor.current_power_production
icon: mdi:home-lightning-bolt-outline
show_state: true
button_action:
  tap_action:
    action: navigate
    navigation_path: '#energy'
sub_button:
  - entity: sensor.electricity_counter
    icon: mdi:counter
    show_background: false
    show_state: true
    tap_action:
      action: more-info
  - entity: sensor.today_s_energy_production
    show_state: true
    show_background: false
  - entity: sensor.average_daily_consumption
    show_background: false
    show_state: true
  - entity: sensor.this_week_production
    show_state: true
    show_background: false
    icon: mdi:calendar-week

Tap, double tap and hold actions

You can also use Home Assistant default tap actions, double tap actions and hold actions on the cards that supports this option. For example, this allows you to display the “more info” window by holding a button icon or running a service when a sub-button is pressed.

Action options

<summary>Options (YAML + description)</summary>

Example

type: custom:bubble-card
card_type: button
button_type: name
name: Kitchen
icon: mdi:fridge
button_action:
  tap_action:
    action: navigate
    navigation_path: '#kitchen'

Styling

You can add custom styles in the editor or by adding styles: | in YAML without using card-mod which allows you to modify the CSS style of all the cards.

[!TIP]
To understand which style classes can be modified, you can take a look at the src/cards folder in this repository. In each card folder, you will find a file named styles.ts. These files contain all the applied styles.

You can also find a lot of examples on the Home Assistant forum by doing a bit of searching.

The Bubble theme for Home Assistant (like on the screenshots) can be found here.

[!IMPORTANT]
Please note that you will have to add !important; to some CSS styles that are already defined (see examples below).

Examples

styles: |
  * { 
    font-size: 16px !important;
  }

styles: >
  /* Selector for the '#kitchen' button */
  .kitchen > .color-background {
    background-color: blue !important;
  }

styles: | 
  .bubble-button-card-container {
    background: rgba(12,120,50,0.5) !important;
  }

To change the color when it's on take a look at the style templates below.

styles: |
  .bubble-range-fill { 
    background: rgba(79, 69, 87, 1) !important;
    opacity: 1 !important;
  }

styles: |
  .bubble-line {
    background: var(--primary-text-color);
    opacity: 0.1;
  }

styles: |
  .bubble-icon {
    color: white !important;
  }

For an horizontal buttons stack icon.

.kitchen > .bubble-icon {
  color: grey !important
}

styles: |
  .bubble-icon-container {
    background: rgb(230, 128, 41);
  }

styles: |
  .bubble-sub-button {
    height: 48px !important;
    min-width: 48px !important;
  }

styles: |
  .bubble-sub-button-2 {
    background-color: blue !important;
  }

For the main icon.

styles: |
  .bubble-icon {
    --mdc-icon-size: 26px !important;
  }

For the sub-button icons.

styles: |
  .bubble-sub-button-icon {
    --mdc-icon-size: 26px !important;
  }

sub_button:
  - icon: none
styles: |-
  .bubble-sub-button-1 {
    background-image: url("/local/pictures/your_picture.jpg");
    background-size: cover;
  }

Just upload this picture in a “pictures” folder (or the name you want) in the Home Assistant “www” folder.

I really love this one, I use it as a header on my dashboard.

type: custom:bubble-card
card_type: button
card_layout: large
button_type: name
show_icon: false
show_name: false
sub_button:
  - name: Mute
    icon: mdi:volume-off
    tap_action:
      action: toggle
      service: input_boolean.toggle
    entity: input_boolean.silent_mode
  - name: Covers
    entity: cover.all_group
    show_background: false
    tap_action:
      action: navigate
      navigation_path: '#cover'
  - name: Shopping list
    icon: mdi:cart-outline
    show_background: false
    tap_action:
      action: navigate
      navigation_path: '#shopping-list'
  - name: Security
    icon: mdi:video-outline
    show_background: false
    tap_action:
      action: navigate
      navigation_path: '#security'
  - name: Settings
    icon: mdi:cog
    show_background: false
    tap_action:
      action: navigate
      navigation_path: '#configuration'
styles: |
  .card-content {
    width: 100%;
    margin: 0 !important;
  }
  .bubble-button-card-container {
    background: none;
  }
  .bubble-sub-button {
    height: 46px !important;
    width: 46px !important;
  }
  .bubble-sub-button-container {
    width: 100%;
    justify-content: space-between !important;
  }
  .bubble-sub-button-icon {
    --mdc-icon-size: inherit !important;
  }
  .bubble-name-container {
    margin-right: 0px !important;
  }

Templates

Bubble Card doesn’t support Jinja templates but advanced users can add templates in JS directly in their custom styles. For example, this allows you to dynamically change an icon, the texts or the colors of an element, to show or hide an element conditionally (like a sub-button), or almost anything based on a state, an attribute and more.

[!TIP]
More information about JS templates here. My advice is to always take a look at your browser console to be sure that everything is working correctly.

Available variables and functions

You have access to these variables in most cards:

• state will return the state of your defined entity.

• entity will return your entity you defined like switch.test in this example.

• icon can be used like this to change the icon icon.setAttribute("icon", "mdi:lightbulb").

• subButtonIcon[0] can be used like this to change the first sub-button icon subButtonIcon[0].setAttribute("icon", "mdi:lightbulb"), [0] is the first sub-button icon, [1] the second...

• card will return the card element in the DOM.

• hass is an advanced variable that allows you even more control, for example you can return the state of light.kitchen like this hass.states['light.kitchen'].state or an attribute like this hass.states[entity].attributes.brightness.

• this will return a lot of usefull informations about your setup and dashboard, only use this if you know what you are doing.

You have access to all the global JS functions, but you have also access to:

• getWeatherIcon can be used to return a weather icon based on a state that return the weather. For example, you can can do this ${subButtonIcon[2].setAttribute("icon", getWeatherIcon(hass.states['sensor.weather_forecast_daily'].attributes.forecast[0]?.condition))} to change the third sub-button icon to today's weather icon, .forecast[1]?.condition is for tomorrow...

  You will have to create a template sensor for that. Here is what you can add in your configuration.yaml:

    - trigger:
        - platform: time_pattern
          hours: /2
      action:
        - service: weather.get_forecasts
          data:
            type: daily
          target:
            entity_id: weather.home
          response_variable: daily
      sensor:
        - name: Weather Forecast Daily
          unique_id: weather_forecast_daily
          state: "{{ now().isoformat() }}"
          attributes:
            forecast: "{{ daily['weather.home'].forecast }}"
  

Examples

type: custom:bubble-card
card_type: button
entity: switch.test
name: Test
styles: |
  .bubble-button-background {
    opacity: 1 !important;
    background-color: ${state === 'on' ? 'blue' : 'red'} !important;
  }

styles: |
  .kitchen > .color-background {
    background-color: ${hass.states['light.kitchen'].state === 'on' ? 'blue' : 'red'} !important;
  }

This one is showing the first sub-button only when my vacuum is stuck.

styles: |
  .bubble-sub-button-1 {
    display: ${hass.states['vacuum.downstairs'].state === 'error' ? '' : 'none'} !important;
  }

This one is showing a sub-button when the battery is below 10%. Usefull with a sub-button that shows "Low battery".

styles: |
  .bubble-sub-button-1 {
    display: ${hass.states['vacuum.downstairs'].attributes.battery_level <= 10 ? '' : 'none'} !important;
  }

This one is changing a button icon only when a vacuum is stuck.

styles: |
  ${icon.setAttribute("icon", hass.states['vacuum.downstairs'].state === 'error' ? 'mdi:alert' : 'mdi:robot-vacuum')}

This one is changing the first sub-button icon only when a vacuum is stuck.

styles: |
  ${subButtonIcon[0].setAttribute("icon", hass.states['vacuum.downstairs'].state === 'error' ? 'mdi:alert' : 'mdi:robot-vacuum')}

This one is changing a button icon color based on its state.

styles: |
  .bubble-icon {
    color: ${hass.states['light.your_light'].state === 'on' ? 'green' : 'red'} !important;
  }

This one is changing a sub-button icon color based on its state. .bubble-sub-button-1 is the first sub-button, replace 1 if you want to change another sub-button icon.

styles: |
  .bubble-sub-button-1 > ha-icon {
    color: ${hass.states['light.your_light'].state === 'on' ? 'green' : 'red'} !important;
  }

This one is rotating a button icon when a fan is on.

styles: |-
  .bubble-icon {
    animation: ${hass.states['fan.you_fan'].state === 'on' ? 'slow-rotate 2s linear infinite' : ''};
  }
  @keyframes slow-rotate {
    0% { transform: rotate(0deg); }
    100% { transform: rotate(360deg); }
  }

This one is changing a button name/state with "It's currently sunny" depending on your weather.

styles: |
  ${card.querySelector('.bubble-name').innerText = "It's currently " + hass.states['weather.home'].state}

If you want to template the state (.bubble-state) don't toggle show_state: true just toggle show_attribute: true without any attribute.

styles: |
  ${window.addEventListener('location-changed', () => { 
  card.querySelector('.bubble-sub-button-1').style.backgroundColor = this.location.href.includes('#kitchen') ? 'blue' : '';
  })}

You can use hass.formatEntityState(state) to transtale a state and hass.formatEntityAttributeValue(state, "attribute") to translate an attribute.

This one is changing the name and the icon based on the weather, "Nuageux" means "Cloudy" in French.

type: custom:bubble-card
card_type: separator
icon: mdi:weather-cloudy
sub_button:
  - entity: sensor.outside_temperature
    icon: mdi:thermometer
    name: Temperature
    show_state: true
    show_background: false
styles: >
  .bubble-line {
    background: white;
    opacity: 1;
  }

  ${card.querySelector('.bubble-name').innerText =
  hass.formatEntityState(hass.states['weather.maison'])}

  ${icon.setAttribute("icon",
  getWeatherIcon(hass.states['weather.maison'].state))}

Custom components conflicts

⚠️ For now there are some features that are not working with:

• Kiosk mode, but this is fixed in Kiosk mode v6.0.1

Help

Feel free to open an issue if something is not working as expected.

Got questions or thoughts about Bubble Card? Want to share your dashboards or discoveries? You can go on the Home Assistant forum, on the Bubble Card subreddit or on the GitHub Discussions section.

Donate

I dedicate most of my spare time to making this project the best it can be. So if you appreciate my work, any donation would be a great way to show your support 🍻

Thank you everyone for your support, you all are my greatest motivation!