Actions for different parts of a button card

[lisz8]

I'd like to share some methods to trigger separate actions for different parts of the awesome button card (currently it allows a separate action only for the icon).

---

Basic idea

The basic idea of the first method is to retrieve a list of HTML elements "under the pointer", and based on this, decide what action to run. Let's say you want separate tap actions for the state field and the custom field named my_room, and no action for other parts of the button. Then all you have to do is this:

tap_action:
  action: javascript
  javascript: |
    [[[
      const ACTIONS = {
        state: {action: 'more-info', entity: 'sensor.some_sensor'},
        my_room: {action: 'navigate', navigation_path: '/some/path'},
        'default action': {action: 'none'},
      };
      const KEYS = Object.keys(ACTIONS);
      
      let elements = this.shadowRoot?.querySelectorAll(':hover') ?? [];
      let filtered = Array.from(elements)
        .filter(el => KEYS.includes(el.id))
        .map(el => el.id);
      let actionKey = filtered.length > 0 ? filtered[0] : 'default action';
      helpers.runAction(ACTIONS[actionKey]);
    ]]]

To reuse this example, only the ACTIONS object needs to be changed. It will also work for hold_action, etc.

Advanced template

I created an "advanced" template that covers all types of button actions: tap, hold, double tap, press and release. It supports overlapping elements (e.g. you can have a separate actions for a custom field and elements contained in that field). You can define actions in an (almost) normal way: create them as variables. The pattern looks like this:

variables:
  tap_action:                            (optional)
    key1:
      action: more-info
      entity: sensor.some_sensor
      element_actions_id: ...            (optional)
      element_actions_priority: ...      (optional)
    key2:
      ...
    default_action:                      (optional)
      ...
  hold_action:                           (optional)
    key1:
      ...
    ...
  ...
  element_actions_control_ripple: true   (optional, defaults to false)

key1, key2, etc. are the identifiers of the elements that should trigger the action. These may include custom field names or 'name', 'state', 'label', and others. The key can be overridden by an optional element_actions_id, and then it can become a descriptive/friendly name of the action.

default_action key denotes the default action of a given type (tap/hold/etc.). By default it's set to no action.

element_actions_priority is the second optional entry: specifies what action to execute when elements overlap (default priority is 0, and a higher value wins).

The action itself is defined in a normal way. You can use any kind of action (more-info, toggle, perform-action, navigate, url, assist, none). You can even use javascript to define actions for this template, but first make sure to read the hidden paragraph below.

Using javascript for actions definition

There could be some edge cases, so take this informations with a grain of salt.

The code enclosed in three square brackets [[[ ]]] will be executed only once, during the button card initialization. This is very different from normal behavior, as it doesn't re-execute when the card is updated. You can restore the standard behavior by setting variables.element_actions_volatile: true. It is so because I cache the action definitions, as they usually do not change.

Code enclosed in four square brackets [[[[ ]]]] will be executed only when actions are performed. But note the difference between calculating a value for a field and executing the code as an action E.g. both of the following code snippets will be executed on every tap_action:

variables:
  tap_action:
    some_key:
      action: "[[[[ javascript code ]]]]"
    another_key:
      action: "[[[[ another javascript code ]]]]"

To run javascript as an action, use the javascript action that is specifically designed for this purpose. This time, each piece of code will only be executed when an action is performed for a specific element (some_key or another_key):

variables:
  tap_action:
    some_key:
      action: javascript
      javascript: "[[[[ javascript code ]]]]"
    another_key:
      action: javascript
      javascript: "[[[[ another javascript code ]]]]"

This also works:

variables:
  tap_action:
    some_key:
      action: "[[[[ if (...) return 'none' else return 'javascript' ]]]]"
      javascript: "[[[[ javascript code ]]]]"

The following code will never run because the key made_up_name is not expected in the context of more-info.

variables:
  tap_action:
    some_key:
      action: more-info
      made_up_name: "[[[[ console.log(...) ]]]]"

Code enclosed in 4 brackets is not affected by element_actions_volatile: true.

--- end of "Using javascript for actions definition"

Press/release and tap/hold/double tap actions are mutually exclusive.

element_actions_control_ripple is a "global" variable that can be set to true. In this case, the template will disable the hover effect for the card (by setting --button-card-ripple-hover-opacity to 0), and the press effect will only be visible if an actual action other than none is defined for the pressed item.

Template "element_actions1"

element_actions1:
  variables:
    element_actions_control_ripple: false
    element_actions_volatile: false
    2de80548-fcfc-43c6-9cea-69b313bb39fa: |
      [[[
        /* version 1.1 tested with custom button card 7.0.1 */
        
        const NO_ACTION = {action: 'none'};
        const DEFAULT_ACTION_ID = '6424c735-c5f9-48e9-8348-0b2414e96e0a';
        const DEFAULT_ACTION = {element_actions_id: DEFAULT_ACTION_ID, action: NO_ACTION.action};

        return (this['2de80548-fcfc-43c6-9cea-69b313bb39fa'] ??= {
          card: this,
          cache: new Map(),
          existing: [],
          selected: {},
          rippleHidden: false,
          getFromCache(aType, tConfig) {
            let ret = this.cache.get(aType);
            if (!ret) {
              if (!tConfig) throw new Error(`element_actions1, getFromCache: missing tConfig`);
              function repack(entry) {
                if (!entry?.action) return NO_ACTION;
                let def = {...entry};
                for (const k of ['element_actions_priority','element_actions_id']) {
                  if (typeof def[k] !== 'undefined')
                    delete def[k];
                }
                return def;
              };
              const arr = Object.entries(tConfig)
                .map(([k,v]) => [
                  typeof v?.element_actions_id !== 'undefined' ? v.element_actions_id : k, 
                  {
                    priority: v?.element_actions_priority ?? 0,
                    definition: repack(v),
                  }
                ]);
              ret = new Map(arr);
              this.cache.set(aType, ret);
            }
            return ret;
          },
          isAction(a) {
            if (!a?.action || a.action === 'none') return false;
            return true;
          },
          shouldCreateButtonAction(aType) {
            function isObject(o) { return o !== null && typeof o === 'object' && !Array.isArray(o); };
            let tConfig = isObject(variables[aType]) ? variables[aType] : {};
            if (!isObject(tConfig.default_action))
              tConfig.default_action = DEFAULT_ACTION;
            else if (tConfig.default_action.element_actions_id !== DEFAULT_ACTION_ID)
              tConfig.default_action.element_actions_id = DEFAULT_ACTION_ID;

            if (!this.actionsAdjusted) {
              this.actionsAdjusted = true;
              if (this.shouldCreateButtonAction('press_action') || this.shouldCreateButtonAction('release_action')) {
                this.tap_action_disabled = true;
                this.hold_action_disabled = true;
                this.double_tap_action_disabled = true;
              } else {
                this.press_action_disabled = true;
                this.release_action_disabled = true;
              }
            }
            if (this[`${aType}_disabled`]) return false;
            const lookup = this.getFromCache(aType, tConfig);
            if (lookup.size === 1) {
              const actionKey = DEFAULT_ACTION_ID;
              const a = lookup.get(actionKey).definition;
              if (!this.isAction(a)) return false;
            }
            return true;
          },
          getButtonActionDefinition(aType) {
            if (this.shouldCreateButtonAction(aType)) {
              if (!this.existing.includes(aType)) this.existing.push(aType);
              return {
                action: 'javascript',
                javascript: `
                  [[[
                    variables['2de80548-fcfc-43c6-9cea-69b313bb39fa']
                      .executeAction('${aType}');
                  ]]]
                `,
              };
            } else {
              return NO_ACTION;
            }
          },
          selectAction(aType) {
            const lookup = this.getFromCache(aType);
            let actionKey;
            if (lookup.size === 1) {
              actionKey = DEFAULT_ACTION_ID;
            } else {
              let elements = this.card.shadowRoot?.querySelectorAll(':hover') ?? [];
              let filtered = Array.from(elements)
                .filter(el => lookup.has(el.id))
                .map(el => el.id)
                .sort((a,b) => lookup.get(b).priority - lookup.get(a).priority);
              actionKey = filtered.length > 0 ? filtered[0] : DEFAULT_ACTION_ID;
            }
            const a = lookup.get(actionKey).definition;
            this.selected[aType] = this.isAction(a) ? a : null;
            return this.selected[aType];
          },
          executeAction(aType) {
            if (!variables.element_actions_control_ripple)
              this.selectAction(aType);
            const a = this.selected[aType];
            if (a) helpers.runAction(a);
          },
          handlePointerDown() {
            if (this.throttleId) return;
            this.throttleId = setTimeout(() => { this.throttleId = null; }, 250);

            let hideRipple = true;
            this.existing.forEach(t => {
              if (this.selectAction(t)) hideRipple = false;
            });

            if (hideRipple !== this.rippleHidden) {
              let r = this.card.shadowRoot?.querySelector('ha-ripple');
              if (r) {
                if (hideRipple) r.style.setProperty('visibility','hidden');
                else r.style.removeProperty('visibility');
                this.rippleHidden = hideRipple;
              } else {
                console.warn('element_actions1 set to hide ripple but no ha-ripple was found');
              }
            }
          },
          cardUpdate() {
            if (variables?.element_actions_volatile) {
              this.existing = [];
              this.actionsAdjusted = false;
              this.cache.clear();
              this.tap_action_disabled = false;
              this.hold_action_disabled = false;
              this.double_tap_action_disabled = false;
              this.press_action_disabled = false;
              this.release_action_disabled = false;
            }

            if (variables?.element_actions_control_ripple) {
              this.card.updateComplete.then(() => {
                if (!this.buttonHandlerAdded) {
                  this.card.addEventListener(
                    'pointerdown',
                    (e) => {
                      if (e.target === e.currentTarget)
                        this.handlePointerDown();
                    },
                    { passive: true }
                  );
                  this.buttonHandlerAdded = true;
                }
              });
            }
            return this;
          },
        }).cardUpdate();
      ]]]
  tap_action: |
    [[[
      return variables?.['2de80548-fcfc-43c6-9cea-69b313bb39fa']
        ?.getButtonActionDefinition('tap_action');
    ]]]
  hold_action: |
    [[[
      return variables?.['2de80548-fcfc-43c6-9cea-69b313bb39fa']
        ?.getButtonActionDefinition('hold_action');
    ]]]
  double_tap_action: |
    [[[
      return variables?.['2de80548-fcfc-43c6-9cea-69b313bb39fa']
        ?.getButtonActionDefinition('double_tap_action');
    ]]]
  press_action: |
    [[[
      return variables?.['2de80548-fcfc-43c6-9cea-69b313bb39fa']
        ?.getButtonActionDefinition('press_action');
    ]]]
  release_action: |
    [[[
      return variables?.['2de80548-fcfc-43c6-9cea-69b313bb39fa']
        ?.getButtonActionDefinition('release_action');
    ]]]
  styles:
    card:
      - '--button-card-ripple-hover-opacity': |
          [[[
            return variables?.element_actions_control_ripple ? '0'
              : 'var(--button-card-ripple-hover-opacity)';
          ]]]

Example 1: tap/hold/double tap

type: custom:button-card
template: element_actions1
show_label: true
name: Name (tap, hold & double tap)
label: Label (tap=default, hold=own)
custom_fields:
  field1: field1 (no action)
  field2: |
    [[[
      return `
        <span style="display: flex;gap: 16px;">
        <ha-icon icon="mdi:home"
          id="icon-with-aciton"
          style="width: 40px;color: var(--info-color);">
        </ha-icon>
        field2 (tap, hold & double tap,<br>
        for both field and icon)
        </span>
      `;
    ]]]
  info: |
    [[[
      return `
        There's a default tap action. Every field 'inherits'
        <br>that action, unless overridden for that field.
      `;
    ]]]
variables:
  element_actions_control_ripple: false
  tap_action:
    name:
      action: more-info
      entity: sensor.name__tap
    field1:
      action: none
    this key may be descriptive, then use element_actions_id:
      action: more-info
      entity: sensor.field2__tap
      element_actions_id: field2
    icon-with-aciton:
      action: more-info
      entity: sensor.icon-with-aciton__tap
      element_actions_priority: 1
    default_action:
      action: toast
      toast:
        message: Default action (tap)!
  hold_action:
    name:
      action: more-info
      entity: sensor.name__hold
    label:
      action: more-info
      entity: sensor.label__hold
    field2:
      action: more-info
      entity: sensor.field2__hold
    icon-with-aciton:
      action: more-info
      entity: sensor.icon-with-aciton__hold
      element_actions_priority: 1
  double_tap_action:
    name:
      action: more-info
      entity: sensor.name__double_tap
    field2:
      action: more-info
      entity: sensor.field2__double_tap
    icon-with-aciton:
      action: more-info
      entity: sensor.icon-with-aciton__double_tap
      element_actions_priority: 1
styles:
  card:
    - padding: 8px 0px
  grid:
    - display: flex
    - flex-direction: column
    - gap: 16px
  label:
    - align-self: center
  name:
    - align-self: center
  custom_fields:
    field1:
      - cursor: default
    info:
      - order: -1
      - font-size: 14px
      - color: var(--info-color)
section_mode: true
grid_options:
  rows: 4
  columns: 9

Example 2: press/release with javascript actions

type: custom:button-card
template: element_actions1
show_label: true
name: Press, wait, release
label: "[[[ return variables.memory.labelText; ]]]"
variables:
  element_actions_control_ripple: true
  press_action:
    name:
      action: javascript
      javascript: |
        [[[[  // <--- 4 brackets!
          /* start a timer to count 3 seconds */
          variables.memory.startTimer();
          /* force redraw of button card to show changed label */
          this.update();
        ]]]]
  release_action:
    name:
      action: javascript
      javascript: |
        [[[[  // <--- 4 brackets!
          variables.memory.makeResult();
          /* force update to show result */
          this.update();
        ]]]]
  memory: |
    [[[
      /* storage object attached to the button card survives card updates */
      const MID = 'my-memory-object-1';
      this[MID] ??= {
        card: this,
        clearTimer() {
          if (this.timer) {
            clearInterval(this.timer);
            this.timer = 0;
          }
        },
        startTimer() {
          this.clearTimer();
          this.seconds = 2;
          this.labelText = '2';
          this.timer = setInterval(
            /* function runs every second for max 3 seconds */
            () => {
              if (--this.seconds === 0) {
                this.labelText = 'Go!';
              } else if (this.seconds > 0) {
                this.labelText = `${this.seconds}`;
              } else if (this.seconds == -1) {
                this.clearTimer();
                this.labelText = '...';
              }
              /* force redraw */
              this.card.update();
            },
            1000
          );
        },
        makeResult() {
          this.clearTimer();
          this.labelText = this.seconds == 0 ? 'Success!'
            : this.seconds > 0 ? 'Too soon!' : 'Too late!';
        },
      };
      return this[MID];
    ]]]
styles:
  card:
    - cursor: default
  grid:
    - display: flex
    - gap: 16px
  name:
    - border: 2px solid
    - padding: 6px
    - margin-left: 12px
    - cursor: pointer
  label:
    - align-self: center
    - font-size: 20px
    - font-weight: 500

---

A second general method is to manually attach event listeners/handlers to elements in the DOM. It is harder because you can't use the Home Assistant's actions (tap/hold/...). Instead, you chose the event(s) of the HTML element, and write javascript code to handle them. It's tricky because some events only work on PC, while others only work on mobile. Another challenge is avoiding adding the same event handler multiple times. You may also need to enable pointer-events for the card (card's style). I only used this method to simulate tap actions, with the 'pointerup' event, which seems to be working on both PC and mobile.

I created a template to make it a bit easier and prevent mistakes.

Template "element_actions2"

element_actions2:
  variables:
    addAction: |
      [[[
        return (id, evName, handler, ...args) => {
          variables['ef70bfec-fcdb-4ce2-bc35-fe06179de5f5'].add(id, evName, handler, args);
        }
      ]]]
    ef70bfec-fcdb-4ce2-bc35-fe06179de5f5: |
      [[[
        /* event handlers are added on each button card update, as every update can change elements in the DOM */
        this.updateComplete.then(() => {
          const storageObj = variables['ef70bfec-fcdb-4ce2-bc35-fe06179de5f5'];
          for (const [, cfg] of storageObj.Handlers) {
            let el = this.shadowRoot.getElementById(cfg.id);
            if (!el) {
              console.warn('element_actions2: element not found, id:', cfg.id);
            } else {
              /* handler/listener to add; a "fixed" wrapper prevents adding multiple copies of the same handler */
              cfg.wrapper ??= function(e) {
                e.stopPropagation();
                cfg.handler(e, cfg.args);
              };
              el.addEventListener(cfg.evName, cfg.wrapper, { passive: true });
            }
          }
        });

        /* storage for the handlers */
        return (this['ef70bfec-fcdb-4ce2-bc35-fe06179de5f5'] ??= {
          get Handlers() { return (this.handlers ??= new Map()); },
          add(id, evName, handler, ...args) {
            if (!(id && evName && handler)) return;
            const key = `${id} ${evName}`;
            /* en entry for each handler must only be created once but the handler
               function or its arguments may change every time the card is updated
            */
            if (this.Handlers.has(key)) {
              let cfg = this.Handlers.get(key);
              cfg.handler = handler;
              cfg.args = args;
            } else {
              this.Handlers.set(key, {id,evName,handler,args});
            }
          },
        });
      ]]]

Example

type: custom:button-card
template: element_actions2
show_riple: false
custom_fields:
  my_field: |
    [[[
      /* event handler for the icon */
      const ICON_ID = 'icon-with-aciton';
      variables.addAction(
        ICON_ID,
        'pointerup',
        (e,...args) => {
          /*
            e - event object
            ...args or [arg1, arg2] - additional arguments passed to addAction
          */
          helpers.runAction({
            action: 'toast',
            toast: {
              message: `ID: ${e.target.id},
                args: ${args}`
            }
          });
        },
        'argument1',
        new Date().toTimeString(),
      );

      /* event handler for the custom field itself */
      variables.addAction(
        'my_field',
        'pointerup',
        (e) => {
          function rand() { return Math.floor(Math.random()*200) };
          function randomColor() { return `rgb(${rand()},${rand()},${rand()})`;};
          let el = e.currentTarget;
          el.style.setProperty('border-color', randomColor());
        }
      );
      
      /* custom field definition */
      return `
        <span style="
          display: flex;
          gap: 16px;
          align-items: center;
          cursor: pointer;
        ">
        <ha-icon icon="mdi:presentation-play"
          id="${ICON_ID}"
          style="width: 24px; color: var(--info-color);">
        </ha-icon>
        my icon has own action
        <span>
      `;
    ]]]
  my_field2: |
    [[[
      /* force update of the card - border color resets, and the time argument refreshes */
      variables.addAction(
        'my_field2',
        'pointerup',
        (e) => {
          this.update();
        }
      );
      return 'update card';
    ]]]
styles:
  card:
    - pointer-events: auto
  grid:
    - display: flex
    - gap: 16px
    - padding: 4px
  custom_fields:
    my_field:
      - border: 2px solid
      - cursor: pointer
      - padding: 4px
    my_field2:
      - cursor: pointer

---

The final method is to place javascript code directly within the HTML definition. This is considered bad practice but is supported by all browsers. The main drawback is that this method cannot be applied to any of the standard parts of the button card (name, label, custom fields, etc.). I no longer use this method and recommend against it.