UIX actions

UIX has several custom actions which can be used on Home Assistant Frontend dashboards. These are invoked using action: fire-dom-event with a uix: object to set the action and any parameters set in the data: object. UIX actions can be used on any card that supports the fire-dom-event action which includes all standard Home Assistant cards.

# ... card config
  tap_action:
    action: fire-dom-event
    uix:
      action: <action>
      data:
        <action-data>

clear-cache - clearing Home Assistant Frontend cache

Clears the Home Assistant Frontend Application cache and reloads the Browser - localStorage remains untouched. This can be very convenient especially for devices where the option is hidden in a debugging menu and will also clear more than just the Frontend Application cache (e.g. localStorage which clears out many stored items like Browser Mod Browser ID).

Example button to clear cache and reload.

show_name: true
show_icon: true
type: button
name: Clear Frontend Cache
tap_action:
  action: fire-dom-event
  uix:
    action: clear-cache

event - dispatch a browser event

Dispatches a CustomEvent on window. This is useful for connecting a button action to a UIX Broker interaction in the browser realm without adding a fire-dom-event listener that unwraps another event.

For a normal dashboard action, the event is dispatched on window. For a UIX Broker button directive, UIX automatically dispatches from the button's placement reference — its after target, before target, or directive anchor — with bubbles: true and composed: true. The receiving Broker interaction can therefore use an event-path anchor such as target, <, or <$; it does not need to re-search from an absolute select_tree path.

For example, this Broker button dispatches toggle-yaml-mode from its placement reference:

- type: button
  before: $ ha-automation-sidebar $$ ha-automation-sidebar-card $ ha-dialog-header slot:nth-of-type(3) ha-dropdown
  icon: mdi:code-braces
  tap_action:
    action: fire-dom-event
    uix:
      action: event
      name: toggle-yaml-mode
      data:
        source: sidebar-button

more-info - show Home Assistant more-info for an entity with starting view

Shows the Home Assistant more-info dialog with the option to set the starting view of the more-info dialog.

Example showing more-info with history view.

type: tile
entity: light.bed_light
tap_action:
  action: fire-dom-event
  uix:
    action: more-info
    data:
      entity: light.bed_light
      view: history

toast - show Home Assistant toast notification

Shows a Home Assistant toast notification.

Example toast with action with translated action text.

type: tile
entity: light.bed_light
tap_action:
  action: fire-dom-event
  uix:
    action: toast
    data:
      message: "Bed Light"
      duration: 10000
      dismissable: true
      bottomOffset: 550
      action:
        primary: true
        text:
          translationKey: ui.dialogs.more_info_control.light.toggle
        tap_action:
          action: perform-action
          perform_action: light.toggle
          target:
            entity_id: light.bed_light
      secondary_action:
        text: Custom
        tap_action:
          action: perform-action
          perform_action: light.toggle
          target:
            entity_id: light.ceiling_lights

javascript - run javascript code in Browser session

Runs JavaScript code in the browser session with hass provided and an optional variables object.

Example javascript action with variable and using hass object to turn off a light.

type: tile
entity: light.bed_light
tap_action:
  action: fire-dom-event
  uix:
    action: javascript
    data:
      variables:
        entity_id: light.bed_light
      code: |
        console.log("UIX: Custom javascript action executed!");
        hass.callService("light", "turn_off", {}, { entity_id: variables.entity_id });

locked_action - require a code or confirmation before an action

Runs a normal Home Assistant action only after the current user passes the configured lock. It is useful for actions such as restarts, opening gates, or changing a critical setting without needing to wrap the entire card in a Forge lock.

type: button
name: Restart Home Assistant
tap_action:
  action: fire-dom-event
  uix:
    action: locked_action
    data:
      locks:
        - code: 1234
          admins: true
      locked_action:
        action: perform-action
        perform_action: homeassistant.restart

Configuration reference

locked_action accepts any ordinary Home Assistant action object, including perform-action, toggle, more-info, navigate, and fire-dom-event.

Lock matching

locks is an ordered list. The first matching active entry determines the challenge. If no active entry matches, the first matching active: false entry allows the action without a challenge.

admins is additive: without it, admins are excluded from an entry unless listed in users. When no lock entry matches, permissive: true permits the action; with the default permissive: false, admins bypass the action guard and non-admins cannot run the action.

Lock entry keys

Code dialog

Use code_dialog to customise the code or passphrase prompt.

Retry tracking

Retry state is retained in the current browser session. Set id whenever a retry delay or lockout matters, especially if dashboard configuration can be regenerated by a template or another custom card: an explicit ID survives control recreation. The same ID shares a retry count, so different protected actions should use different IDs.

tap_action:
  action: fire-dom-event
  uix:
    action: locked_action
    data:
      id: restart-home-assistant
      code_dialog:
        title: Enter administrator PIN
        submit_text: Restart
      locks:
        - code: 1234
          admins: true
          max_retries: 3
          max_retries_delay: 5m
      locked_action:
        action: perform-action
        perform_action: homeassistant.restart