custom:button-card

custom:button-card is a highly customizable button designed for Home Assistant Lovelace interfaces. It allows for deep integration with any entity and provides extensive control over styling, actions, and animations.

Key Capabilities:

• Entity Integration: Works with any Home Assistant entity.
• Flexible Actions: Supports 6 standard actions (none, toggle, more-info, navigate, url, assist, and call-service) on tap, hold, or double click.
• Granular Interaction:
  • Icon Tap Action: Define a specific action for clicking the icon that takes precedence over the main card action.
  • Momentary Actions: Use press_action and release_action to replace default tap behaviors.
  • Custom Actions: Supports javascript, multi-actions, and toast actions.
  • Security: Includes password/PIN protection for sensitive actions and a locking mechanism.
• Advanced Styling:
  • Color Management: Supports icon color type (applies to icon only) and card color type (applies to card and automatically adjusts font color).
  • Dynamic Styling: Custom colors based on light RGB values or temperature, and custom state definitions (color, icon, and style).
  • Layout & Sizing: Supports custom icon sizes, width/height, aspect ratio, and multiple layout modes.
  • CSS: Full support for custom CSS styling.
• Animations & Feedback:
  • Native blink animation support.
  • Icon rotation animation support.
  • Haptic feedback support for the iOS companion app.
• Organization:
  • Blank cards and label cards for UI organization.
  • Ability to redefine or hide sensor units.

When nesting a custom:button-card inside the custom_fields of another custom:button-card, you must use quadruple brackets [[[[ ... ]]]] if you want the inner card to evaluate the template itself.

If you use triple brackets [[[ ... ]]] in a nested configuration, the outer card will evaluate the template and pass the resulting value (a string) to the inner card. If you use quadruple brackets [[[[ ... ]]]], the outer card will strip one pair of brackets and pass the template code to the inner card, allowing the inner card to evaluate the logic dynamically.

type: custom:button-card
entity: sensor.skylight
custom_fields:
  nested:
    card:
      type: custom:button-card
      entity: light.bed_light
      name: |
        [[[[
          return entity?.state === 'on' ? 'Light On' : 'Light Off';
        ]]]]
styles:
  grid:
    - grid-template-areas: '"nested"'

The multi-actions action type allows you to execute multiple actions in a sequence with optional delays.

Important Limitations:

• This runs exclusively in the browser. If you navigate away from the page while actions are queued, they will not execute.
• Actions are fired back-to-back without waiting for the previous action to finish (unless using wait_completion).
• Nested actions do not support repeat, repeat_limit, sound, confirmation, protect, or haptic properties; these will be ignored.

Special Entries in the actions array:

• delay: Accepts a string (natural language like 3s or 1min) or a number (milliseconds). Supports templating.
• wait_completion: Accepts a JS template that must return true or false. The sequence waits (checking every 0.5s) until the template returns true. You can specify a timeout (same format as delay).

type: 'custom:button-card'
icon: mdi:console
name: multi-actions
tap_action:
  action: multi-actions
  actions:
    - action: call-service
      service: light.toggle
      service_data:
        entity_id: light.test_light
    - delay: '3s'
    - action: javascript
      javascript: '[[[ helpers.toastMessage(`Done!`); ]]]'

The card supports various interaction triggers including tap, hold, and double click.

Available Actions

You can assign the following actions to triggers:

• none: No action.
• toggle: Toggles the entity state.
• more-info: Opens the entity's more-info dialog.
• navigate: Navigates to a specific dashboard view.
• url: Opens an external URL.
• assist: Triggers Home Assistant Assist.
• call-service: Calls a specific Home Assistant service.

Advanced Interaction Features

• Icon Tap Action: You can define a separate action specifically for clicking the icon, which takes precedence over the main card actions.
• Momentary Actions: Use press_action and release_action to define behavior for the duration of a press. Note that using these replaces the default tap/hold/double-click actions.
• Custom Actions: Supports javascript, multi-actions, and toast actions.
• Security: Supports confirmation popups for sensitive items and password/PIN protection for specific actions.

The custom:button-card offers deep styling capabilities:

Color and Icon Styling

• Color Types:
  • icon: Applies color settings only to the icon.
  • card: Applies color settings to the card itself (includes automatic font color adjustment).
• State-based Styling: Define custom state definitions with unique colors, icons, and styles.
• Custom Icons: Supports custom icon sets and rotation animations.

Layout and Dimensions

• Sizing: Control icon size, card width, and card height.
• Aspect Ratio: Supports defined aspect ratios for the card.
• Layouts: Supports multiple built-in layouts and custom layout configurations.
• Units: Ability to redefine or hide units for sensor entities.

Animations and Feedback

• Blink Animation: Native support for blinking states.
• Icon Rotation: Support for rotating icons.
• Haptics: Supports haptic feedback for the iOS companion app.

Variables allow you to reuse logic and values across multiple fields. They can be any type (string, number, object, function).

Note: Variables are only evaluated if they are used. If a variable is defined but never referenced, it will not be evaluated.

Simple Usage

You can define a variable once and reference it in multiple style or name fields.

type: custom:button-card
entity: switch.skylight
variables:
  color_on: green
  color_off: red
  is_on: '[[[ return entity.state === "on"; ]]]'
  color: |
    [[[ 
      if (variables.is_on) return variables.color_on; 
      else return variables.color_off; 
    ]]]
styles:
  icon:
    - color: '[[[ return variables.color; ]]]'

Using Variables as Functions

You can store functions in variables to perform complex logic.

type: custom:button-card
variables:
  myFunc: |
    [[[ 
      return (str) => { return `${str} from myFunc()`; } 
    ]]]
name: '[[[ return variables.myFunc("Nice Name"); ]]]'

Variable Dependencies

Variables can depend on other variables, but circular dependencies (loops) are prohibited and will cause failure.

Advanced: Forcing Variable Evaluation

By default, variables are only evaluated if used. To force a variable to evaluate every time the card updates (useful for advanced JS logic), use the force_eval: true property:

variables:
  varName:
    force_eval: true
    value: '[[[ ... ]]]'