Adapted from the canonical English UIX documentation by Lint-Free-Technology/uix, CC BY 4.0. Source: dev / 9.0.0-beta.2, revision 26e54e6, reviewed 22 October 2026. This source mirror may describe preview behavior beyond stable 8.4.0. Markup adapted for this site; the original documentation remains authoritative.

Overlay Icon spark

The overlay-icon spark overlays an icon on any element inside a UIX Forge forged element.

• If entity is set, the spark renders a ha-state-icon.
• If image_url is set, the spark renders a div with the image as background-image.
• Otherwise it renders a ha-icon.

The icon can come from:

• a fixed MDI or custom icon (icon)
• an image URL (image_url)
• an entity state icon (entity)

Basic usage

type: custom:uix-forge
forge:
  mold: card
  sparks:
    - type: overlay-icon
      for: hui-tile-card $ ha-tile-icon
      icon: mdi:shimmer
element:
  type: tile
  entity: light.bed_light

Configuration reference

Top-level keys

Key	Type	Default	Description
type	string	—	Must be overlay-icon.
for	string	element	UIX selector for the element to overlay. When the UIX Forge element is using Blank card config, the default is uix-forge-blank-card $ div.content. Otherwise, the default of element refers to the root of the forged element.
icon	string	—	MDI/custom to show. Use one of icon or image_url
image_url	string	—	Static image applied as overlay. Supports media-source:// URIs. Use one of icon or image_url.
entity	string	—	If provided a state icon is rendered (ha-state-icon). When entity is set, icon and image_url are ignored.
value	string	—	If entity is provided you can override the state value used to generate the icon.
color	string	state	If entity is provided set the icon color when the entity is active for the overlay icon. By default, the color is based on the state, domain, and device_class of the entity. To take default color, set to none. It accepts state, none, a Home Assistant color token, or a hex color code. Default color when none is set is var(--white-color) when target is ha-tile-icon, otherwise var(--primary-color)
icon_color	string	var(--white-color) when target is ha-tile-icon, otherwise var(--primary-color)	CSS color for the icon. Overrides color if set.
icon_position	object	when target is hui-generic-entity-row: {top: '8px', left: '30px'}; when target is ha-tile-icon: {top: '2px', left: '30px'}; otherwise not set	Pixel offsets for the icon inside the overlay. Accepts any combination of top, bottom and left, right. Numbers are treated as pixels; strings accept any CSS value. left takes precedence over right. top takes precedence over bottom. NOTE: Due to the overlay mechanism of the icon in the overlay container, right is set as left: calc(100% - var(--uix-overlay-icon-size, <icon_size>) - <icon_position.right>) and bottom is set as top: calc(100% - var(--uix-overlay-icon-size, <icon_size>) - <icon_position.bottom>)
icon_size	number or string	12px when target is ha-tile-icon, 24px otherwise	Size of the icon. Numbers are treated as pixels; strings are passed through as-is.
icon_background	CSS background	var(--primary-color) when target is ha-tile-icon, otherwise not set	Explicit CSS background for the icon (overrides the default background-color behavior).

Customizing the overlay appearance

The overlay icon respects CSS custom properties. Set these on the forged element's uix.style (or in a theme):

CSS variable	Default	Description
--uix-overlay-icon-z-index	1	Stack order of the overlay.
--uix-overlay-icon-display	block	CSS display of the overlay.
--uix-overlay-icon-opacity	1 when target is ha-tile-icon; 0.5 otherwise	Opacity of the overlay (icon and background combined).
--uix-overlay-icon-border-radius	inherit	Border radius of the overlay (inherits the target's).
--uix-overlay-icon-row-border-radius	--uix-overlay-icon-border-radius	Border radius of the overlay when the forge mold is row.
--uix-overlay-icon-border	unset	Border style CSS.
--uix-overlay-icon-size	24px; 12px when target is ha-tile-icon	Size of the icon. Overrides icon_size from spark config.
--uix-overlay-icon-color	var(--primary-color); var(--white-color) when target is ha-tile-icon	Icon color.
--uix-overlay-icon-background	transparent; var(--primary-color) when target is ha-tile-icon	Background color of the icon element when icon_background is not explicitly set.
--uix-overlay-icon-border-radius	none; 50% when target is ha-tile-icon	Border radius of the icon element.
--uix-overlay-icon-padding	0; 2px when target is ha-tile-icon	Padding around the icon.
--uix-overlay-icon-position	none	CSS translate value applied to the icon (e.g. 30px 6px). Both icon_position if set and --uix-overlay-icon-position will combine to provide the final icon position.

WARNING

As rows in entities card are displayed inline (display: inline) deeper element targeting cannot take place as overlays do not work with elements displayed inline. This means overlay-icon spark can only apply to an entire entity row.

INFO

Overlay-based sparks set position: relative on the targeted element when its computed position is static, so the absolute overlay can be anchored correctly.

Examples

Tile icon overlay badge

type: custom:uix-forge
forge:
  mold: card
  sparks:
    - type: overlay-icon
      for: hui-tile-card $ ha-tile-icon
      icon: mdi:check-decagram
      icon_color: white
      icon_background: "#22b922"
element:
  type: tile
  entity: light.bed_light

INFO

For non-entity overlays, when multiple icon source keys are set the spark resolves precedence as: image_url → icon.

Entity-driven overlay icon with value override

type: entities
entities:
  - type: custom:uix-forge
    forge:
      mold: row
      sparks:
        - type: overlay-icon
          for: $ hui-generic-entity-row
          entity: sensor.outside_temperature_battery
          state_color: true
          value: "10"
      uix:
        style: |
          :host {
            --uix-overlay-icon-opacity: 1;
          }
    element:
      entity: light.bed_light

Overlay icon on a button showing the number of lights on (max 9)

Uses a macro to translate number of lights on to a circle number icon.

An extra button is used to change the state of one light for the animated example.

type: custom:uix-forge
forge:
  macros:
    icon:
      params:
        - group_id
      template: |
        {% set icons =
           { 0: 'mdi:numeric-0-circle',
             1: 'mdi:numeric-1-circle',
             2: 'mdi:numeric-2-circle',
             3: 'mdi:numeric-3-circle',
             4: 'mdi:numeric-4-circle',
             5: 'mdi:numeric-5-circle',
             6: 'mdi:numeric-6-circle',
             7: 'mdi:numeric-7-circle',
             8: 'mdi:numeric-8-circle',
             9: 'mdi:numeric-9-circle',
           }
        %}
        {% set lights = state_attr(group_id, 'entity_id')
          | expand
          | selectattr('state', 'eq', 'on')
          | list
          | count %}
        {% set iconIndex = [lights, 9] | min %}
        {{ icons[iconIndex] }}
  mold: card
  sparks:
    - type: overlay-icon
      icon: |
        {{ icon(config.element.entity) }}
      icon_size: 36px
      icon_color: |
        {{ "var(--state-active-color)" if is_state(config.element.entity, "on")  else "var(--state-inactive-color)" }}
      icon_position:
        left: calc(100% - 36px - 6px)
        top: 6px
element:
  show_name: true
  show_icon: true
  type: button
  entity: light.all_lights

Overlay icon with media source image_url and styling to show as a popover style badge

type: custom:uix-forge
forge:
  mold: card
  sparks:
    - type: overlay-icon
      for: hui-button-card $ ha-card $
      icon_size: 36
      image_url: media-source://media_source/local/daniel_craig_cropped.jpg
  uix:
    style: |
      :host {
        --uix-overlay-icon-opacity: 1;
        --uix-overlay-icon-border-radius: 50%;
        --uix-overlay-icon-position: 0px -16px;
      }
element:
  type: button
  entity: light.bed_light
  uix:
    style: |
      ha-card {
        overflow: visible !important;
      }

Overlay icon on button icon

TIP

If the icon does not show check if the icon should be applied to the target shadowRoot. e.g. overlay icon will not show with for: hui-button-card $ ha-state-icon but will show with for: hui-button-card $ ha-state-icon $. For the former, it will add to DOM but will not show due to DOM structure.

type: custom:uix-forge
  forge:
    mold: card
    sparks:
      - type: overlay-icon
        for: hui-button-card $ ha-state-icon $
        icon: mdi:shimmer
        icon_color: white
        icon_background: "#22b922"
    uix:
      style: |
        :host {
          --uix-overlay-icon-border-radius: 50%;
          --uix-overlay-icon-position: 20px;
          --uix-overlay-icon-opacity: 0.9;
        }
  element:
    show_name: true
    show_icon: true
    type: button
    entity: light.bed_light

Overlay icon in custom:template-entity-row

TIP

Sometimes the target may just be the element shadowRoot or a div under the shadowRoot. To place an overlay icon in custom:template-entity-row use for: $ #wrapper. You will need to adjust the position to match the position applied automatically by the hui-generic-entity-row target adapter.

type: entities
  entities:
    - type: custom:uix-forge
      forge:
        mold: row
        sparks:
          - type: overlay-icon
            for: "$ #wrapper"
            entity: sensor.outside_temperature_battery
            state_color: true
            value: "10"
            icon_position:
              top: 8px
              left: 30px
        uix:
          style: |
            :host {
              --uix-overlay-icon-opacity: 1;
            }
      element:
        type: custom:template-entity-row
        entity: light.bed_light