Directives

Directives run one at a time after every interaction rule matches. Each directive performs one configured operation, using the interaction anchor by default or an explicitly selected directive anchor where supported. Except for block, a directive may also have its own rules; the directive runs only when all of them match, otherwise Broker skips it and continues with the next directive.

• Block — prevent the initiating browser event's default action and propagation.
• Property — set or clear a JavaScript object property.
• Event — dispatch a CustomEvent.
• Call — invoke an element method.
• Button — insert an interactive Home Assistant button.
• Tile icon — insert an interactive Home Assistant tile icon.
• Tooltip — attach a styled tooltip to an element.
• Action — run a Home Assistant, frontend, or UIX action.
• Template — render a Jinja2 template once and save its result.
• JavaScript — synchronously evaluate JavaScript and save its return value.
• Wait — delay the next directive.

Directive rules

Add rules to any directive except block to condition just that directive. The syntax is the same as interaction rules. For property, event, call, button, tile-icon, and tooltip, host-element rules inspect the resolved directive anchor by default. For action and wait, they inspect the interaction anchor. A rule's own anchor remains relative to that default anchor, or can be absolute as usual.

directives:
  - type: property
    set: config.mode
    value: advanced
  - type: call
    method: openAdvancedEditor
    rules:
      - type: captured
        path: allow_advanced
        match: true

panel rules obtain the current panel state when the directive is reached. This lets an earlier directive run regardless of the current panel while a later directive only runs on a matching panel.

block does not accept directive rules. Put its condition in the interaction's rules so that the event is synchronously blocked only when the complete interaction matches.

Block

block calls preventDefault() and stopImmediatePropagation() on the initiating browser event.

- type: block

It is available only in browser and shortcut realms. The interaction anchor and host-element rule anchors must resolve synchronously; if a required select_tree anchor is not already present, UIX Broker skips the complete interaction. A block directive is applied before the remaining directives are processed, even when it appears later in the list.

Directive anchors

property, event, call, button, tile-icon, and tooltip directives use the interaction anchor by default. Each can override that default with its own anchor configuration. A bare string is relative to the interaction anchor, a string beginning with & is a compact absolute document-root select_tree path, and { select_tree: ... } is the equivalent long absolute form.

directives:
  - type: property
    anchor: "$ ha-dialog"
    set: withoutHeader
    value: true
  - type: event
    anchor: "&home-assistant $$ ha-automation-sidebar"
    name: broker-sidebar-event
  - type: call
    anchor:
      select_tree: "home-assistant $ ha-more-info-dialog"
    method: closeDialog

Use the uix_broker_path($0) console helper in the browser console to find a relative directive-anchor path.

See Interaction Anchors for the selection formats.

See Finding paths in the browser console for more information on the console helpers available.

Property

property directive changes the selected anchor's JavaScript object. set takes a dot-separated property path, creates any missing intermediate plain-object levels, and assigns the value at the final property. clear takes the same kind of path and deletes only the final property; it does not remove its parent objects.

- type: property
  set: config.heading
  value: New title
- type: property
  clear: config.icon

Values can refer to captured data or a previous template or javascript result. @captured resolves to the complete captured-data object, while @captured.path resolves to the value at that dot-separated path. Array indexes can use either dot notation (items.0) or brackets (items[0]); use a quoted bracket key for object properties that contain punctuation, such as settings['icon-color']. The reference is substituted before the property is set and must be quoted in YAML as it starts with @.

- type: property
  set: config.entity
  value: "@captured.entity_id"

template and javascript directives save their value under their id. A later directive can use @id or a property such as @id.path; the value keeps its original type, including objects and arrays. References occupy a complete YAML value — Broker does not interpolate them into a longer string.

Event

event dispatches a CustomEvent. Its target defaults to anchor, meaning the selected directive anchor (or the interaction anchor when no directive anchor is set). Set target: window or target: document to dispatch globally instead; these targets do not use or resolve an event-specific directive anchor. bubbles and composed default to false, matching the DOM API.

- type: event
  name: broker-demo-event
  bubbles: true
  composed: true
  data:
    entity: light.bed_light

- type: event
  target: window
  name: broker-window-event
  data:
    source: uixBroker
- type: event
  target: document
  name: broker-document-event

Set capture_data: true to copy captured event data into a modified event. The outgoing event's detail starts with the initiating interaction's captured data, then shallowly overlays values from this directive's data object. The capture_data option is only available to the event directive.

- type: event
  name: broker-forwarded-event
  capture_data: true
  data:
    source: uixBroker

Set capture_data: deep when nested plain objects should be merged instead. Directive data wins for conflicting values; arrays and non-plain objects are replaced as complete values. This leaves capture_data: true unchanged.

- type: event
  name: broker-forwarded-event
  capture_data: deep
  data:
    params:
      source: uixBroker

Call

call invokes a method on the selected anchor. method accepts a safe dot-separated method path and preserves the method object's this binding. args, when provided, must be an array and supports captured-data substitution.

- type: call
  method: focus
- type: call
  method: setSelectionRange
  args: [0, 5]

Button

button inserts a Home Assistant ha-button beside the directive anchor. It uses the same button configuration and action handling as the Forge button spark. The button is inserted after the directive anchor by default.

Use after or before to select a different reference element. These paths are relative to the resolved directive anchor and support the usual UIX select_tree syntax. The button is still inserted as a sibling of the matched reference element.

- type: button
  label: Toggle
  entity: light.living_room
  tap_action:
    action: toggle

- type: button
  anchor: "$ ha-dialog"
  before: "div.header"
  label: Toggle
  entity: light.living_room
  tap_action:
    action: toggle

Use style for a flat mapping of CSS property names and values. The properties are set inline on the generated ha-button, which is useful for button dimensions and spacing that cannot be styled from dashboard configuration.

- type: button
  anchor: "$ div.menu div.title"
  icon: mdi:hammer
  color: red
  size: s
  tap_action:
    action: navigate
    navigation_path: /config/tools
  style:
    "--ha-button-box-shadow": rgba(0, 0, 0, 0.1) 0px 4px 12px
    "--ha-icon-button-size": 32px

Use uix for UIX styling, including styles inside the button's shadow root. Its UIX type is uix-broker-button; the resolved button settings are available as config, and prior template or javascript directive results are available as directive in UIX templates.

- type: button
  entity: light.living_room
  label: Toggle
  uix:
    style: |
      :host {
        --uix-button-margin: {{ '6px' if is_state(config.entity, 'on') else '0px' }};
      }

Tile icon

tile-icon inserts a Home Assistant ha-tile-icon beside the directive anchor. It uses the same icon rendering and action handling as the Forge tile-icon spark. The tile icon is inserted after the directive anchor by default.

Use after or before to select a different reference element. These paths are relative to the resolved directive anchor and support the usual UIX select_tree syntax. The tile icon is inserted as a sibling of the matched reference element.

- type: tile-icon
  entity: light.living_room
  tap_action:
    action: toggle

- type: tile-icon
  anchor: "$ ha-dialog"
  before: "div.header"
  entity: light.living_room
  icon: mdi:star
  color: orange
  tap_action:
    action: more-info

Use style for a flat mapping of CSS property names and values. The properties are set inline on the generated ha-tile-icon, which is useful for positioning and sizing the icon where dashboard styling cannot reach it.

- type: tile-icon
  entity: light.living_room
  style:
    margin-inline-start: 8px
    "--tile-icon-size": 28px
    z-index: 1

Use uix for UIX styling, including styles inside the tile icon's shadow root. Its UIX type is broker-tile-icon; the resolved tile-icon settings are available as config, and prior template or javascript directive results are available as directive in UIX templates.

- type: tile-icon
  entity: light.living_room
  uix:
    style: |
      :host {
        --tile-icon-size: {{ '32px' if is_state(config.entity, 'on') else '24px' }};
      }

Tooltip

tooltip attaches a Home Assistant wa-tooltip beside the selected target. Its options and CSS variables match the Forge tooltip spark. By default, for is the resolved directive anchor; a selector is relative to that anchor and uses the normal UIX select_tree syntax. The target must resolve to an element, not a terminal shadow root.

- type: tooltip
  content: Open the living-room light controls
  placement: bottom

Use for: previous directly after a UI directive to attach the tooltip to the element it created. It currently works with button and tile-icon, and will work with later element-producing directives without needing an element selector.

- type: button
  icon: mdi:lightbulb
  tap_action:
    action: toggle
- type: tooltip
  for: previous
  content: Toggle the light
  placement: bottom

- type: tooltip
  for: "$ ha-dialog ha-icon-button"
  content: Close
  without_arrow: true

Use style for a flat mapping of CSS properties. This is particularly useful for setting the --uix-tooltip-* variables directly on the generated tooltip.

- type: tooltip
  for: previous
  content: Toggle the light
  style:
    "--uix-tooltip-background-color": var(--primary-color)
    "--uix-tooltip-content-color": white
    "--uix-tooltip-max-width": 24ch

trigger accepts Web Awesome's space-separated hover, focus, click, and manual activation modes. When hover is enabled, the tooltip remains open while the pointer moves from the target into the tooltip body, allowing constrained content to be scrolled. manual does not activate automatically; use open to set its state when the directive runs.

- type: tooltip
  for: previous
  trigger: manual
  open: true
  content: This tooltip is opened by the directive

The tooltip is inserted as a sibling of its target. Set the --uix-tooltip-* CSS variables on the target's parent or an ancestor to customise it; see the Forge tooltip spark CSS variables.

Action

action runs a Home Assistant service call, a standard frontend action, or one of the UIX Broker-specific actions.

- type: action
  action: light.turn_on
  target:
    entity_id: light.example

- type: action
  action: fire-dom-event
  uix:
    action: toast
    data:
      message: Done

JavaScript action

action: javascript is a UIX Broker action. Put the code in data.code. UIX Broker automatically passes hass, anchor, event, and captured as variables. hass is the active Home Assistant object, anchor is the resolved interaction anchor DOM element, event is the initiating event, and captured is the interaction's captured data.

- type: action
  action: javascript
  data:
    code: |
      console.log(anchor, event, captured)

Use JavaScript only from trusted UIX configurations.

Template

template renders a Home Assistant Jinja2 template once through the template API; it does not create a template subscription. Its string result is stored under id for the remaining directives in that interaction.

Every uncached render is a round trip to the Home Assistant server. Avoid using it on interactions that can run frequently. Set cache to a positive number of milliseconds when a slightly stale value is acceptable:

- type: template
  id: example
  cache: 5000
  template: "{{ states('sensor.example') }}"

The cache is held in the browser and shared by template directives using the same template text and prior directive results. A cached value is used only when it is younger than the directive's cache duration; cache: 0 (or omitting cache) always renders again. The cache stores only successful results, is cleared when Broker configuration reloads, and does not observe template changes during the cache period. When cache is enabled, prior directive results must be JSON-serializable because they form part of the cache key; circular objects cannot be cached.

- type: template
  id: log_provider_url
  template: "/config/logs?provider={{ states('input_select.log_provider') }}"
- type: button
  after: "&home-assistant $ home-assistant-main $ ha-config-system-navigation $ ha-config-navigation-list $ ha-list-item-button:nth-of-type(4) $ a#item div.content"
  icon: mdi:open-in-new
  color: var(--primary-color)
  tap_action:
    action: url
    url_path: "@log_provider_url"

id must start with a letter or underscore and can then contain letters, numbers, underscores, and hyphens. The name captured is reserved for @captured event data and cannot be used as an ID. Use dot or bracket array paths to select a saved object or array value, just as for @captured. Quoted bracket keys also work, for example @config_path['icon-color'] or @config_path["icon-color"].

Templates receive prior directive results in the top-level directive variable. For example, a prior directive with id: provider is available as {{ directive.provider }}. This namespace contains only results from earlier directives in the same interaction.

JavaScript

javascript evaluates code once and saves its synchronous return value under id. The code receives hass, anchor, event, captured, and directive; directive contains prior directive results from the same interaction. Return a scalar, object, or array; the following directives can use it as @id without conversion.

- type: javascript
  id: config_path
  code: |
    const provider = hass.states['input_select.log_provider'].state;
    return {
      path: `/config/logs?provider=${provider}`,
      label: `Open ${provider.charAt(0).toUpperCase() + provider.slice(1)} logs`,
    };
- type: button
  icon: mdi:open-in-new
  label: "@config_path.label"
  tap_action:
    action: url
    url_path: "@config_path.path"

Use JavaScript only from trusted UIX configurations.

Wait

Use wait to pause a directive sequence without performing another operation. It requires a non-negative number of milliseconds.

directives:
  - type: wait
    wait: 500
  - type: action
    action: light.turn_on
    target:
      entity_id: light.example

Every directive also accepts wait, a non-negative number of milliseconds. In that form, UIX Broker waits after applying the directive before starting the next one. A block directive always runs synchronously, though it can include wait to delay later directives.

directives:
  - type: event
    name: broker-started-event
    wait: 250
  - type: action
    action: light.turn_on