DOCSEARCHbyAlgolia
Submit Docs

Bubble Card Documentation

repository·main·Indexed 26 days ago

https://github.com/clooos/bubble-card

A minimalist and highly customizable collection of cards for Home Assistant, featuring a unique pop-up system and a module store to enhance dashboard UI/UX. Includes various card types such as button, calendar, climate, cover, media-player, and a horizontal-buttons-stack for navigation. Supports installation via HACS or manual JavaScript resource addition.

Tokens
24.1K
Snippets
52
Records
138
Agent score
88%

What's inside Bubble Card

  1. Use selector-based fields for rich UI controls

    main
    Selector-based fields provide advanced UI controls in the Bubble Card module editor. Instead of using the legacy type syntax, use the selector property with a specific selector type (e.g., text, number, boolean, select, ui_color, icon, condition, entity, device, area, theme, action, time, date, datetime, media, attribute, state, target, config_entry, addon, location, object, backup, assistance, label, language, schedule, template, file, qr_code, conversation_agent, duration, dashboard, or floor).

  2. Configure Sub-buttons in Bubble Card

    main

    Sub-buttons allow you to add custom controls (buttons, sliders, or dropdowns) to any card that supports the sub_button option. You can organize them into main (top) and bottom sections, and use groups to create advanced layouts.

    Layout and Structure

    • main: The primary sub-button section.
    • bottom: A fixed section at the bottom of the card. When present, the card layout automatically switches to large unless specified otherwise.
    • main_layout / bottom_layout: Set to inline (default) or rows to stack groups vertically.
    • Groups: An array of sub-buttons with an optional buttons_layout (inline or column).
    • justify_content: Available for bottom groups only (start, center, end, fill).
    sub_button:
  main:
    - group:
        - entity: sensor.temperature
          show_state: true
          show_background: false
        - entity: sensor.humidity
          show_state: true
          show_background: false
      buttons_layout: column
  bottom:
    - group:
        - entity: light.living_room
        - entity: light.bedroom
      buttons_layout: inline
      justify_content: center
  main_layout: inline
  bottom_layout: rows

  3. Install Bubble Card via HACS (Recommended)

    main

    The recommended way to install Bubble Card is through the Home Assistant Community Store (HACS), which allows for direct updates.

    1. Ensure HACS is installed and configured in your Home Assistant instance.
    2. Navigate to the HACS section in your sidebar.
    3. Search for "Bubble Card".
    4. Click "Download".
    5. Refresh your dashboard. You can now add cards by searching for Bubble Card in the card picker.

  4. Apply a module to a card

    main

    You can apply modules either through the UI editor or via YAML configuration.

    Via the UI Editor:

    1. Open the card editor.
    2. Expand the Modules section.
    3. Select the desired module from the list.
    4. Under "Apply to", select "This card".

    Via YAML: Add the module IDs to the modules list in your card configuration.

    type: custom:bubble-card
card_type: button
entity: light.example
modules:
  - module_id_1
  - module_id_2

  5. Apply a module globally to all cards

    main

    To make a module apply to all Bubble Cards automatically, you can use the editor or YAML. Note that modules with a custom configuration UI (Editor) cannot be applied globally because they require specific per-card configuration.

    Via the UI Editor: In the My Modules tab, find your module and toggle the All cards button.

    Via YAML: In your bubble-modules.yaml file, add is_global: true to the module definition.

  6. Create a new Bubble Card Module

    main

    You can create custom modules to save and reuse CSS or JavaScript templates across your dashboard.

    1. Open any card's editor and expand the Modules section.
    2. Click Create new module.
    3. Fill in the module information (name, version, etc.).
    4. Write your CSS and/or JavaScript template code in the Code editor. Module code works identically to the styles section of a card.
    5. (Optional) Define a custom configuration UI in the Editor section using Home Assistant form options.
    6. Click Save.

  7. Access configuration values in module code

    main

    To access values configured by users in your module's code section, use the this.config object. Values are accessed via a path that includes your module's ID and the field's name property.

    Access Pattern: this.config.module_id?.field_name

    Best Practices:

    • Use optional chaining (?.): Always use optional chaining when accessing nested properties to prevent errors if the configuration is missing.
    • Provide default values: Use the OR operator (||) to supply fallback values if a configuration is undefined.

    Example: If your module ID is my_module and you have a field named size with a default of 24:

    --mdc-icon-size: ${this.config.my_module?.size || 24}px;
    # Example Editor Schema
editor:
  - name: color
    label: "Background Color"
    selector:
      ui_color: {}
  - name: size
    label: "Icon Size"
    selector:
      number:
        min: 10
        max: 50
        unit_of_measurement: "px"
  - name: show_icon
    label: "Show Icon"
    selector:
      boolean: {}

# Example Code usage
.bubble-icon-container {
  /* Access the "color" field */
  background: var(--${this.config.module_id?.color}-color) !important;
  
  /* Access the "size" field with a default value if undefined */
  --mdc-icon-size: ${this.config.module_id?.size || 24}px;
  
  /* Access the "show_icon" boolean field */
  display: ${this.config.module_id?.show_icon ? 'flex' : 'none'};
}

  8. Exclude a global module from a specific card

    main

    If a module is set to apply globally, you can exclude it from a specific card using the UI or YAML.

    Via the UI Editor: In the card's Modules section, locate the global module and disable the "This card" option.

    Via YAML: Use the ! prefix before the module ID in the modules list.

    type: custom:bubble-card
card_type: button
entity: light.example
modules:
  - !global_module_id

  9. Register Bubble Card as a dashboard resource in Home Assistant

    main

    If you are using a local build for the first time, you must manually register the resource in your Home Assistant dashboard:

    1. Open your dashboard and click the pencil icon (Edit dashboard).
    2. Click the three-dot menu and select Manage resources.
    3. Click Add resource.
    4. Enter the URL: /local/bubble-card.js?v=1
    5. Select JavaScript module and confirm.

    For subsequent builds, you only need to clear your browser cache to see changes.

  10. Use JavaScript templates in Bubble Card

    main

    Bubble Card does not support Jinja templates. Instead, advanced users can use JavaScript templates directly within the styles configuration to dynamically modify elements.

    Important Rules:

    • Templates that modify elements (like icons, text, or visibility) instead of CSS properties must be placed at the end of your styles block.
    • Always monitor your browser console to debug template errors.

    Common use cases include changing icons, updating text, modifying colors, or conditionally showing/hiding elements based on entity states or attributes.

  11. Define an editor schema for Bubble Card modules

    main

    An editor schema is an array of objects that defines the user interface presented to users when configuring your module. Each object in the array represents a single form field.

    Common field properties include:

    • name (string, Required): The key used to store the value in the module configuration.
    • label (string): The displayed name for the field in the UI.
    • required (boolean): Whether the field must be filled out.
    • disabled (boolean): Whether the field is disabled in the UI.
    • default (any): The default value used if no value is provided.
    editor:
  - name: color
    label: "Color"
    selector:
      select:
        options:
          - label: "Red"
            value: "red"
          - label: "Blue"
            value: "blue"
  - name: icon_size
    label: "Icon Size"
    selector:
      number:
        min: 20
        max: 50
        unit_of_measurement: "px"

  12. Apply custom styles to Bubble Cards

    main

    You can modify the CSS of Bubble Cards without using card-mod through four primary methods:

    1. Editor UI: Navigate to Styling options > Custom styles & JS templates on the specific card.
    2. Modules: Use the Modules section in the editor to create a new module (available to all cards) or install a module from the Module Store.
    3. Home Assistant Theme: Add CSS variables to your theme YAML file for global modifications. Note that you must run the frontend.reload_themes action to apply changes.
    4. YAML Configuration: Add a styles: | block directly to your card configuration.

    Note: You may need to append !important; to your CSS rules to override existing styles.