Badge spark

The badge spark inserts a uix-badge as a DOM sibling immediately before or after an element within a forged element. It uses Home Assistant's patched Web Awesome badge base and styles, so its colors automatically follow the active Home Assistant theme.

When the target is an ha-button or ha-tile-icon, UIX automatically shows the badge on that element using compact styling. These are the only targets with automatic placement.

uix-badge is namespaced to UIX. UIX does not import or register Web Awesome's global wa-badge component.

Basic usage

Add a badge entry to forge.sparks with either after or before to locate the reference element.

type: custom:uix-forge
forge:
  mold: card
  sparks:
    - type: badge
      after: hui-tile-card $ ha-tile-icon
      content: 3
      variant: danger
      pill: true
element:
  type: tile
  entity: light.bed_light

Configuration

Automatic placement

UIX automatically places badges on exactly two Home Assistant elements:

For these targets, after and before identify the element that receives the badge; they do not control sibling insertion. Without placement, every other target type keeps normal sibling behavior.

The built-in Home Assistant Button card (hui-button-card) does not contain an ha-button; it uses slots for its icon and label. Without placement, it has normal sibling behavior. Set placement to position the badge on the Button card's parent.

UIX does not automatically position badges on arbitrary buttons, cards, or custom elements. Those elements have different slots and layout rules, so placement on their parent is enabled only when placement is explicitly set.

Placement on other elements

Setting placement on any other target positions the badge at the edge of that target's parent. UIX keeps the badge outside the target and does not measure or alter the selected target.

This is useful when the target fills its parent, such as a built-in Button card inside its card container. If the parent contains several visible elements, the placement is relative to the whole parent rather than one child. Use --uix-badge-offset-x and --uix-badge-offset-y for final adjustment.

All placement modes use Home Assistant's compact --ha-font-size-xs font size and tight 0.25em 0.5em padding by default, keeping badge size consistent.

Offsets accept CSS percentages as well as lengths. For a right, top-end, or bottom-end badge, set --uix-badge-offset-x: -50% to cancel the default half-width corner overlap and align every badge by its logical end edge, regardless of content width. Combine it with a length when needed, for example calc(-50% - 20px). For left, top-start, or bottom-start, use 50% to align the logical start edge instead.

Set placement using the same values as wa-tooltip: top, top-start, top-end, bottom, bottom-start, bottom-end, left, left-start, left-end, right, right-start, and right-end. ha-button and ha-tile-icon default to top-end. For every other target, providing placement positions the badge on the parent; omitting it keeps the badge as a normal sibling.

CSS variables

Set these variables on uix-badge or an ancestor. For a single Forge or Broker badge, use its style map. They work for both Forge and Broker badges.

The color variables, including their -hover forms, are passed directly to CSS. They accept any CSS color value, including translucent rgba() or modern space-separated rgb() values with an alpha channel.

With attention: pulse, --uix-badge-box-shadow remains as static shadow layers and UIX appends the expanding pulse ring.

Placed badges accept pointer input, so their hover colors apply only while the pointer is over the badge itself.

For example, this moves a placed badge two pixels inward from its resolved end edge:

type: custom:uix-forge
forge:
  mold: card
  sparks:
    - type: badge
      after: hui-tile-card $ ha-tile-icon
      content: 3
      variant: danger
      pill: true
      style:
        "--uix-badge-offset-x": -2px
        "--uix-badge-offset-y": -2px
element:
  type: tile
  entity: light.bed_light

Examples

Status badge

ha-tile-info is styled to flex: 1 so it shrinks to allow room for the added badge sibling.

type: custom:uix-forge
forge:
  mold: card
  sparks:
    - type: badge
      after: hui-tile-card $ ha-tile-info
      content: Experimental
      variant: warning
      appearance: outlined
      start_icon: mdi:flask-outline
element:
  type: tile
  entity: light.bed_light
  uix:
    style: |
      ha-tile-info {
        flex: 1;
      }

Attention badge

type: custom:uix-forge
forge:
  mold: card
  sparks:
    - type: badge
      after: hui-tile-card $ ha-tile-icon
      content: |
        {{ '!' if is_state('cover.hall_window', 'open') else '⎷' }}
      variant: |
        {{ 'danger' if is_state('cover.hall_window', 'open') else 'success' }}
      pill: true
      attention: |
        {{ 'pulse' if is_state('cover.hall_window', 'open') else 'none' }}
element:
  type: tile
  entity: cover.hall_window

Generic Button-card placement

The built-in Button card does not have automatic badge placement. Because it fills this Forge card's parent, an explicit placement safely positions the badge there without touching the Button card's internal DOM.

type: custom:uix-forge
forge:
  mold: card
  sparks:
    - type: badge
      after: hui-button-card
      content: 3
      variant: danger
      pill: true
      placement: top-end
      style:
        "--uix-badge-offset-x": -6px
        "--uix-badge-offset-y": 6px
        "--uix-badge-font-size": 24px
element:
  type: button
  entity: light.bed_light

Badge on a button spark

A Forge button spark uses a display: contents wrapper. A later badge spark can target that wrapper, as shown below; UIX recognises it and attaches the badge to the contained ha-button rather than placing it beside the wrapper.

type: custom:uix-forge
forge:
  mold: card
  sparks:
    - type: button
      after: hui-tile-card $ ha-tile-icon
      label: Living Room
    - type: badge
      after: "hui-tile-card $ div[data-uix-forge-button-id]"
      content: 3
      variant: danger
      pill: true
element:
  type: tile
  entity: light.bed_light

UIX Blank card badge

Show a badge as a card using UIX Forge blank card. UIX styling is used to style card border and background as unset so the badge itself remains as the main UI element. UIX Styling of ha-card in shadow root of uix-forge-blank-card justifies the badge to be centered horizontally.

type: custom:uix-forge
forge:
  mold: card
  grid_options:
    columns: 3
  sparks:
    - type: badge
      after: uix-forge-blank-card $ div.content
      content: Badge Spark
      variant: brand
      start_icon: mdi:badge-account-horizontal-outline
  uix:
    style:
      .: |
        :host {
          --ha-card-border-width: 0px;
          --ha-card-background: none;
        }
      uix-forge-blank-card $: |
        ha-card {
          display: flex;
          justify-content: center;
        }