Bubble Card Module Editor schema documentation

This documentation covers all available options for creating editor schemas in Bubble Card modules. These schemas define the user interface presented to users when configuring your module.

Table of contents

• Basic structure
• Accessing configuration values in your module code
  • Accessing configuration in JavaScript templates
  • Tips for working with configuration values
  • Example: Complete module with editor and code
• Field properties
• Field types
  • Selector-based fields
    • Text input selector
    • Number selector
    • Boolean selector
    • Select selector
    • Color selector
    • Icon selector
    • Condition selector
    • Entity selector
    • Device selector
    • Area selector
    • Theme selector
    • Action selector
    • Time selector
    • Date selector
    • Datetime selector
    • Media selector
    • Attribute selector
    • State selector
    • Target selector
    • Config entry selector
    • Addon selector
    • Location selector
    • Object selector
    • Backup selector
    • Assistance selector
    • Label selector
    • Language selector
    • Schedule selector
    • Template selector
    • File selector
    • QR code selector
    • Conversation agent selector
    • Duration selector
    • Dashboard selector
    • Floor selector
  • Legacy type-based fields
    • String field
    • Integer field
    • Float field
    • Boolean field
    • Select field
    • Multi-select field
• Advanced structure
  • Grid layout
  • Expandable sections
• Best practices
• Example: Complete module editor schema
• References

Basic structure

A module editor schema is an array of objects, where each object represents a form field:

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"

Accessing configuration values in your module code

When creating a Bubble Card module, you'll need to access the values configured by users through the editor. These values are available in your module's code through the this.config object.

Accessing configuration in JavaScript templates

In your module's code section, you can access the configured values using JavaScript template literals. The configuration values follow a specific structure:

this.config.module_id?.field_name

Where:

• module_id is the ID of your module as defined in your module definition
• field_name corresponds directly to the name property of the field in your editor schema

editor:
  - name: color                # This becomes "color" in your code
    label: "Background Color"
    selector:
      ui_color: {}
  - name: size                 # This becomes "size" in your code
    label: "Icon Size"
    selector:
      number:
        min: 10
        max: 50
        unit_of_measurement: "px"
  - name: show_icon            # This becomes "show_icon" in your code
    label: "Show Icon"
    selector:
      boolean: {}

.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'};
}

Tips for working with configuration values

• Use optional chaining: Always use the optional chaining operator (?.) when accessing nested configuration properties to prevent errors if the configuration is missing.

• Provide default values if possible: In some cases, use the OR operator (||) to supply default values in case the configuration value is undefined.

Example: Complete module with editor and code

icon_container_color:
  name: 'Example: Customize the icon container color'
  version: v1.1
  creator: Clooos
  link: https://github.com/Clooos/Bubble-Card/discussions/1231
  unsupported:
    - horizontal-buttons-stack
    - separator
  description: |
    A list of predefined colors to customize the icon container color.
    Configure this module via the editor or in YAML, for example:
    <br><br>
    <code-block><pre>
    icon_container_color: 
        color: light-blue
    </pre></code-block>
  code: |
    .bubble-icon-container {
      opacity: 1 !important;
      background: var(--${this.config.icon_container_color?.color}-color) !important;
    }
  editor:
    - name: color
      label: Color
      selector:
        ui_color:
          include_none: true

Field properties

Every field in your editor schema can have these common properties:

Field types

You can define fields using either the legacy type syntax or the modern selector syntax.

Selector-based fields

Selector-based fields provide rich UI controls. Simply use the selector property with one of the following selector types:

Text input selectors

- name: title
  label: "Title"
  selector:
    text: {}

Number selector

- name: opacity
  label: "Opacity"
  selector:
    number:
      min: 0
      max: 100
      step: 5
      unit_of_measurement: "%"

Boolean selector

- name: show_icon
  label: "Show Icon"
  selector:
    boolean: {}

No additional option for this selector.

Select selector

- name: theme
  label: "Theme"
  selector:
    select:
      options:
        - label: "Light"
          value: "light"
        - label: "Dark"
          value: "dark"
        - label: "Auto"
          value: "auto"
      multiple: false
      custom_value: false
      mode: "dropdown"

Color selector

- name: background_color
  label: "Background Color"
  selector:
    ui_color: {}

Icon selector

- name: custom_icon
  label: "Custom Icon"
  selector:
    icon: {}

No additional option for this selector.

Condition selector

- name: conditions
  label: "Conditions"
  selector:
    condition: {}

The condition selector allows you to define complex conditions based on entity states, numeric values, time, and more. This is especially powerful for creating conditional UI elements or behaviors.

// Example of checking if conditions are met
if (!badgeConfig?.condition || (badgeConfig?.condition && checkConditionsMet([].concat(badgeConfig.condition), hass))) {
  // The condition is met or there is no condition defined
  // Show or activate your component here
}

# Module configuration example
my_module:
  element_to_show:
    condition:
      - condition: state
        entity_id: light.living_room
        state: 'on'
      - condition: numeric_state
        entity_id: sensor.temperature
        above: 20

// In your module code
const elementConfig = this.config.my_module?.element_to_show;
if (!elementConfig?.condition || checkConditionsMet([].concat(elementConfig.condition), hass)) {
  // Show element when living room light is ON and temperature is above 20
}

No additional selector options.

Entity selector

- name: target_entity
  label: "Target Entity"
  selector:
    entity:
      filter:
        domain: light

Device selector

- name: device
  label: "Device"
  selector:
    device:
      filter:
        integration: zwave

Area selector

- name: area
  label: "Area"
  selector:
    area: {}

Theme selector

- name: card_theme
  label: "Card Theme"
  selector:
    theme: {}

Action selector

- name: tap_action
  label: "Tap Action"
  selector:
    action: {}

Time selector

- name: start_time
  label: "Start Time"
  selector:
    time: {}

No additional option for this selector.

Date selector

- name: event_date
  label: "Event Date"
  selector:
    date: {}

Datetime selector

- name: event_datetime
  label: "Event Date and Time"
  selector:
    datetime: {}

Media selector

- name: media
  label: "Media"
  selector:
    media: {}

Attribute selector

This selector works only if combined to an entity selector at the same level. Inside an object selector item, if the entity field next to it is empty the attribute list falls back to the card's configured entity, matching the common runtime pattern where items inherit the card entity.

- name: attribute
  label: "Attribute"
  selector:
    attribute: {}

State selector

This selector works only if combined to an entity selector at the same level.

- name: target_state
  label: "Target State"
  selector:
    state: {}

Target selector

- name: target
  label: "Target"
  selector:
    target:
      entity:
        domain: light

Config entry selector

- name: config_entry
  label: "Integration"
  selector:
    config_entry:
      domain: zwave_js

Addon selector

- name: addon
  label: "Add-on"
  selector:
    addon: {}

Location selector

- name: location
  label: "Location"
  selector:
    location:
      radius: true
      icon: "mdi:home"

Object selector

The object selector lets users enter structured objects defined by a set of sub-fields. Each sub-field uses its own selector (e.g., text, number, icon). It can capture a single object or a list when multiple is true. Use label_field and description_field to control the label and secondary text displayed for each item. The output is an object or a list of objects.

When multiple is true, each item row has a drag handle to reorder the list and a duplicate button that inserts a deep copy of the item right below it.

- name: main_item
  label: "Main item"
  selector:
    object:
      fields:
        name:
          label: "Name"
          selector:
            text: {}
        icon:
          label: "Icon"
          selector:
            icon: {}
      label_field: name
      description_field: icon
      multiple: true

Fields that share a group are rendered together inside a collapsible section (the group name becomes the section title, group_icon its optional icon). The stored configuration stays flat — grouping only affects the editor UI, so adding groups to an existing module is fully backward compatible. Fields without a group render at the top level as usual:

- name: items
  label: "Items"
  selector:
    object:
      fields:
        name:
          label: "Name"
          selector:
            text: {}
        background_color:
          label: "Background color"
          group: "Appearance"
          group_icon: "mdi:palette"
          selector:
            ui_color: {}
        text_color:
          label: "Text color"
          group: "Appearance"
          selector:
            ui_color: {}
      multiple: true

Backup selector

- name: backup
  label: "Backup"
  selector:
    backup:
      integration: google_assistant

Assistance selector

- name: assistance_pipeline
  label: "Assistance Pipeline"
  selector:
    assistance: {}

No additional option for this selector.

Label selector

- name: labels
  label: "Labels"
  selector:
    label:
      multiple: true

Language selector

- name: language
  label: "Language"
  selector:
    language: {}

No additional option for this selector.

Schedule selector

- name: schedule
  label: "Schedule"
  selector:
    schedule: {}

No additional option for this selector.

Template selector

- name: template
  label: "Template"
  selector:
    template: {}

No additional option for this selector.

File selector

- name: config_file
  label: "Configuration File"
  selector:
    file:
      accept: ".yaml,.json"

QR code selector

- name: qr_data
  label: "QR Code Data"
  selector:
    qr_code: {}

No additional option for this selector.

Conversation agent selector

- name: agent
  label: "Conversation Agent"
  selector:
    conversation_agent: {}

No additional option for this selector.

Duration selector

- name: timeout
  label: "Timeout"
  selector:
    duration:
      enable_day: false

Dashboard selector

- name: dashboard
  label: "Dashboard"
  selector:
    dashboard:
      include_dashboards: ["lovelace"]

Floor selector

- name: floor
  label: "Floor"
  selector:
    floor: {}

No additional option for this selector.

Legacy type-based fields

While selector-based fields are recommended, you can also use the legacy type syntax:

String field

- name: title
  label: "Title"
  type: string

Integer field

- name: count
  label: "Count"
  type: integer
  valueMin: 0
  valueMax: 100

Float field

- name: opacity
  label: "Opacity"
  type: float

Boolean field

- name: enabled
  label: "Enabled"
  type: boolean

Select field

- name: mode
  label: "Mode"
  type: select
  options:
    - ["auto", "Automatic"]
    - ["manual", "Manual"]

Multi-select field

- name: features
  label: "Features"
  type: multi_select
  options:
    - ["animations", "Animations"]
    - ["colors", "Custom Colors"]
    - ["icons", "Custom Icons"]

Advanced structure

Grid layout

You can organize fields in a grid layout:

- type: grid
  name: appearance
  schema:
    - name: color
      label: "Color"
      selector:
        select:
          options:
            - label: "Red"
              value: "red"
            - label: "Blue"
              value: "blue"
    - name: size
      label: "Size"
      selector:
        number:
          min: 10
          max: 100

Expandable sections

You can create collapsible sections:

- type: expandable
  name: advanced_settings
  title: "Advanced Settings"
  icon: "mdi:tune"
  expanded: false
  schema:
    - name: animation_speed
      label: "Animation Speed"
      selector:
        number:
          min: 1
          max: 10

Best practices

1. Keep it simple: Only include fields that users actually need to configure
2. Use clear labels: Make field labels descriptive but concise
3. Provide defaults: Set sensible default values where possible
4. Group related fields: Use grid or expandable sections to organize complex options
5. Add descriptions: Use the description property to explain complex options
6. Test your UI: Ensure your form is user-friendly before sharing

Example: Complete module editor schema

editor:
  - name: color_mode
    label: "Color Mode"
    selector:
      select:
        options:
          - label: "Custom Color"
            value: "custom"
          - label: "Theme Color"
            value: "theme"
  - name: custom_color
    label: "Custom Color"
    selector:
      ui_color: {}
  - type: expandable
    title: "Advanced Settings"
    expanded: false
    schema:
      - name: animation
        label: "Animation"
        selector:
          boolean: {}
      - name: animation_speed
        label: "Animation Speed"
        selector:
          number:
            min: 1
            max: 10
            step: 0.1
      - name: opacity
        label: "Opacity"
        selector:
          number:
            min: 0
            max: 100
            unit_of_measurement: "%"

This schema creates a form with a select dropdown for color mode, a color picker, and an expandable section with animation controls. This is the example shown in the screenshot at the top of this documentation.

References

This documentation is based on Home Assistant's form schemas:

• Home Assistant Form Types
• Home Assistant Selectors