card-mod

Card-mod v4 uses different methods to apply styles depending on the card's structure. It is important to distinguish between these three terms:

1. patch/patching: card-mod is injecting code into the element class.
2. application/applying: card-mod applies a card_mod object to an element (usually in the shadowRoot) and its children based on selectors.
3. ignore/ignoring: the element patching code takes no action when running at the element level.

In standard Home Assistant cards (like the tile card), card-mod patches the hui-card level. It uses :host { } for base CSS styles and ha-card { } for card styles. It specifically ignores the ha-card patch in standard structures to avoid conflicts with the standard theming model.

All styles can contain Jinja2 templates processed by the Home Assistant backend. card-mod provides several special variables for use within these templates:

• config: The entire configuration of the card, entity, or badge (e.g., config.entity).
• user: The name of the currently logged-in user.
• browser: The browser_id (requires browser_mod).
• hash: The URL fragment after #.
• panel: A dictionary containing panel/view metadata (e.g., panel.panelTitle, panel.viewNarrow, panel.fullUrlPath).

To debug templates, insert the comment {# card_mod.debug #} anywhere in your template to see binding and update logs in the console.

To style elements inside a #shadow-root, change the style value from a string to a dictionary.

Rules for selectors:

• The key is a selector used via a modified querySelector().
• Use $ to target a #shadow-root. For example, ha-markdown$ selects the shadowRoot of the ha-markdown element.
• Use . to select the current element.
• A chain of selectors is processed one element at a time.
• If a chain ends with $, it selects the shadowRoots of all matching elements.
• Tip: If styles are intermittent, split the chain into multiple steps (e.g., instead of A $ B $ C, use A $ then B $ then C) to allow card-mod to retry finding elements as they load.

card_mod:
  style:
    ha-markdown$: |
      h3 {
        color: purple;
      }
    .: |
      ha-card {
        background: teal;
      }

When creating themes that need to support both standard Home Assistant cards and custom cards (or cards loaded via custom wrappers like layout-card), use dual CSS selectors. This ensures your styles apply regardless of whether the card is patched at the hui-card level or the ha-card level.

Use :host(.my-class) ha-card for cards loaded by the Frontend, and ha-card.myclass for custom cards with divergent structures.

card_mod:
  style: |
    :host(.my-class) ha-card,
    ha-card.myclass {
      background-color: red !important;
    }

Custom cards that do not follow the standard hui-card -> ha-card structure (like button-card) require different targeting strategies:

• Using :host: Since the host card is still patched, you can apply CSS variables via :host { }.
• Legacy ha-card patching: For cards where ha-card is not in the standard location (e.g., inside a div before ha-card), card-mod will patch and apply styles directly to ha-card. In these cases, ha-card { } will work.
• YAML selector paths: You can use specific YAML selector paths to navigate the custom DOM tree.

To run a local demo of card-mod using Docker, navigate to the test directory in the repository and execute the following command. Once running, access the demo at http://localhost:8125 using the credentials below:

• Username: dev
• Password: dev

docker-compose up

If a card does not contain an ha-card or hui-card element, you can wrap it in a custom:mod-card. This creates a container that provides an ha-card element for styling purposes.

type: custom:mod-card
card:
  type: custom:beloved-custom-card
  ...
card_mod:
  style: |
    ha-card {
      ...
    }

Starting with version 4.2.0, you can clear the Home Assistant Application cache and reload the browser using a custom action. This is useful for debugging or when the standard cache clearing options are hidden on your device. This action clears more than just the application cache; it also clears localStorage, which may remove stored items like Browser Mod Browser IDs.

To trigger this, execute a fire-dom-event with the key card_mod and the parameter action: clear_cache. This can be used on any card that supports the fire-dom-event action, including all standard Home Assistant cards.

show_name: true
show_icon: true
type: button
name: Clear Frontend Cache
tap_action:
  action: fire-dom-event
  card_mod:
    action: clear_cache

In entities, glance, or picture-elements cards, you can style individual elements by adding a card_mod parameter directly to the entity or element configuration.

Because these elements are typically wrapped in a shadowRoot, use the :host selector to access the element's styles.

type: entities
entities:
  - entity: light.bed_light
    card_mod:
      style: |
        :host {
          color: red;
        }

You can override the icon and icon color of an <ha-icon> element (used in many cards) by setting specific CSS variables within a card_mod style block:

• --card-mod-icon: Sets the icon (e.g., mdi:bed).
• --card-mod-icon-color: Sets the icon color.
• --card-mod-icon-dim: Set to none to prevent the icon from dimming based on entity state.

- entity: light.bed_light
  card_mod:
    style: |
      :host {
        --card-mod-icon: mdi:bed;
      }