UIX Forge

UIX Forge (custom:uix-forge) is a custom Lovelace element that combines template-driven configuration with additional behaviours called sparks. Use it to:

Forge any standard Home Assistant element from templates, allowing the entire element config to react to entity states, user, browser and other template variables.
Add sparks — self-contained behaviours such that augment the forged element.
Apply UIX styles to the forged element, exactly like any other element. Additionally any spark variables and made available in uixForge template variable.

Basic structure

type: custom:uix-forge
forge:
  mold: card
  # optional sparks, macros, hidden, grid_options …
element:
  type: tile
  entity: "{{ 'sun.sun' }}"
  # any valid element config, templates supported

forge controls how UIX Forge itself behaves; element is the configuration of the Home Assistant element that will be rendered inside it.

Forge options

Key	Type	Allows Templates	Default	Description
`mold`	string		(required)	How the element is forged, with each `mold` handling required forged element behaviours within Home Assistant Frontend. Currently `"card"`, `"badge"`, `"row"`, `"picture-element"` or `"section"`.
`macros`	mapping		—	template macros available to all templates in the forge config.
`hidden`	boolean	✅	`false`	When truthy the element is hidden.
`grid_options`	mapping	✅	—	Lovelace grid options (e.g. `rows`, `columns`) for when `mold` is `card`. Ignored for any other `mold`.
`show_error`	boolean		`false`	When `true`, show the Lovelace error card instead of hiding it when the forged element errors.
`template_nesting`	string		`"<<>>"`	Four-character string used to escape `{{ }}` in templates. Use when the element config itself contains Jinja2-like syntax.
`sparks`	list	✅	`[]`	List of spark configurations to attach to the forged element.

Template nesting

When using template nesting, the template nesting characters are replaced with Jinja raw directives before the template is rendered. The replacement includes a marker for internal readiness code to be able to recognise a rendered template with nesting. << is replaced with {% raw %}{{{#uix#}{% endraw %} and >> is replaced with {% raw %}{#uix#}}}{% endraw %}.

Element config

Any valid Lovelace element configuration. Every string value in element is processed as a template, giving access to the same variables as UIX templates (config, user, browser, hash, panel).

The uix key inside element is passed through as is to UIX Styling, with UIX Styling rendering any templates. Use it to style the forged element as you would any other element:

type: custom:uix-forge
forge:
  mold: card
element:
  type: tile
  entity: light.living_room
  uix:
    style: |
      ha-card {
        --tile-color: teal;
      }

UIX styling

Add a uix key under forge to apply UIX styling to the forge element wrapper itself. Template variables config.forge, config.element, and uixForge are available in the style templates, where config.forge and config.element are the resolved forge and element configs and uixForge contains any spark template variables.

type: custom:uix-forge
forge:
  mold: card
  uix:
    style: |
      :host {
        --ha-card-border-radius: 20px;
      }
element:
  type: tile
  entity: light.living_room

Sections

When using UIX Forge for a section in sections view, use the YAML section editor (use three dots menu) and change type to custom: uix-forge. Set forge mold to section.

When using UIX Forge for sections, the following config keys can be set directly to configure how the section shows, though they do not support templates.

type: custom:uix-forge
forge:
  hidden: # use hidden to control visibility
  # ...
element:
  # ...
# section only main configuration keys. Visibility not supported.
row_span: # row span for section
column_span: # column span for section
background: # background for section

When editing the dashboard in UI mode, the section will be surrounded by red dashed border to show that it is configured by UIX Forge in YAML. All cards contained in the section will show in preview mode, but will not be editable. Use YAML for editing the section.

Warning

Visibility in the main config is not supported. Though the Home Assistant visual editor will let you set visibility you will get an error as soon as you save the section. If you need Frontend visibility options not supported by template (screen) use a stack card as your element and set Frontend visibility on that element, templates supported.

Foundries

A foundry is a server-stored UIX Forge template that lets you define reusable forge, element, and uix configs once and share them across many cards. Reference a foundry with the foundry: key and override only what you need locally.

See Foundries for a full guide including merge behaviour, nested foundries, and management via the integration options.

Sparks

Sparks are optional behaviours that you add to the forge.sparks list. Each spark has a type key and its own options.

Available sparks:

Tooltip spark — attach a styled tooltip to any element inside the forged element.
Attribute — add, replace or remove an attribute of any element within the forged element.
Event — receive DOM events from fire-dom-event actions and expose their data as template variables.
Tile Icon — insert a ha-tile-icon element as a sibling before or after any element within the forged element.