Allows you to apply CSS styles to various elements of the Home Assistant frontend.

Install using HACS or see this guide.

While card-mod can be installed as a lovelace resource, some functionality¹ will benefit greatly from it being installed as a frontend module instead.

To do that, add the following to your configuration.yaml file and restart Home Assistant:

frontend:
  extra_module_url:
    - /[card_mod resource URL]

The card_mod resource URL is dependent on where/how you have installed card-mod.js.

• If you installed through HACS, this is likely /hacsfiles/lovelace-card-mod/card-mod.js?hacstag=12345678901.
• If you manage resources due to using YAML mode or are not using HACS your resource url may be different.

When installing through HACS your Dashboard² lovelace resource definition will be automatically added in Dashboard resources which you can access via the button below.

Example Dashboard² lovelace resource definition when installed through HACS.

/hacsfiles/lovelace-card-mod/card-mod.js?hacstag=12345678901

In configuration.yaml add this exact path to frontend: extra_module_url: When updating card-mod through HACS make sure to update your extra_module_url: manually to match. This is critically important as it prevents the resource being loaded twice.

frontend:
  extra_module_url:
    - /hacsfiles/lovelace-card-mod/card-mod.js?hacstag=12345678901

NOTE: If you manage your resource URLs in YAML and do not use CAST, you do not need a resource URL at all. In this case you can just use extra_module_url. It is recommended that you use a cache busting technique to assist with caching of old files on update. e.g. ...\card-mod.js?v4.0.0 updating the version when you update card-mod.

1. Installing card-mod as a Frontend module via extra_module_url will provide performance improvements to non-CAST devices e.g. enhanced speed in applying card-mod to cards, especially when using card-mod themes. Installing card-mod as a Frontend module is also required if you are using card-mod to style panels of Home Assistant which are not Lovelace dashboards, as Dashboard resources are not loaded for those panels. This includes styling the sidebar in your theme for these panels.

2. Dashboard lovelace resource definition is required to enable card-mod to be applied to dashboards on CAST devices.

IMPORTANT:

1. Any resource definitions automatically added by HACS should be kept as is even after adding extra_module_url. This enables you to keep track when updating via HACS.
2. Whenever you alter extra_module_url you need to restart Home Assistant.

• Open your card in the GUI editor
• Click the "SHOW CODE EDITOR" button at the bottom
• Add the following to the bottom of the code:

card_mod:
  style: |
    ha-card {
      color: red;
    }

You should see the text of the card turn red as you type.
You should also see a little brush icon popping up near the "SHOW VISUAL EDITOR" button. This indicates that this card has card-mod code which will not be shown in the visual editor.

Cards are styled by adding the following to the card configuration:

card_mod:
  style: <STYLES>

If the simplest form, <STYLES> is a string of CSS which will be injected into the appropriate element based on the card type. See README-application for a detailed description on where card-mod is applied in version 4, which is slightly different from previous versions.

NOTE: card-mod only works on cards that are contained by a hui-card element, or contain a ha-card element. This includes almost every card standard Home Assistant Frontend cards, and most custom cards.

For a card contained by a hui-card element, which is almost every standard Home Assistant Frontend card, styles are injected into a shadowRoot and the bottom most element is :host, though in most cases the first element in the shadowRoot is ha-card. For many custom cards which do not take advantage of the modern hui-root container, but contain a ha-card element, the styles are injected into ha-card and the bottommost element is ha-card. See README-application for more details.

TIP: Home Assistant themes makes use of CSS variables. Those can both be set and used in card-mod - prepended by two dashes:

card_mod:
  style: |
    ha-card {
      --ha-card-background: teal;
      color: var(--primary-color);
    }

Card_mod version 4 has the prepend option that affects where card_mod styles are injected into the shadowRoot of the card. This is not normally required. However if a card renders in a way that initially has a 'Loading...' or similar initial state, before its final state, prepend may help. When prepend is true, card_mod styles are injected using the prepend function rather than the append function. The option is added at the same level as style.

type: energy-distribution
card_mod:
  prepend: true
  style: |
    ha-card {
      background: red;
    }

Cards known to need prepend option are listed below. Generally these cards will initially have a non-card 'Loading...' state.

• energy-distribution
• energy-sankey
• energy-sources-table
• custom:alarmo-card
• custom:button-state-card
• custom:logbook-card

Prepend examples

Take the following section config for `energy-sankey` with its companion `energy-date-selection`

Without prepend

  type: grid
  cards:
    - type: energy-date-selection
    - type: energy-sankey
      card_mod:
        style: |
          ha-card {
            border-color: red;
          }

Card_mod styles will not show on page load as although card_mod applies, it is removed by the next render of the card.

With prepend: true

type: grid
cards:
  - type: energy-date-selection
  - type: energy-sankey
    card_mod:
      prepend: true # <- add prepend:true here
      style: |
        ha-card {
          border-color: red;
        }

card_mod styles will show correctly on page load.

In entities and glance cards, each entity can have options. Those elements can be styled individually by adding a card_mod parameter to the entity configuration.

For those cases, the styles are injected into a shadowRoot, and the bottommost element is thus accessed through :host.

This also applies to view badges and elements in picture-elements cards.

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

With card-mod installed, the <ha-icon> element - used e.g. by entities, glance and many more cards - will set it's icon to the value found in the CSS variable --card-mod-icon (if present).

It will also set the icon color to the value found in the CSS variable --card-mod-icon-color if present. This ignores entity state, but will still dim unless you also set --card-mod-icon-dim to none.

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

All styles may contain jinja2 templates that will be processed by the Home Assistant backend.

card-mod also makes the following variables available for templates:

• config - The entire configuration of the card, entity or badge - (config.entity may be of special interest)

• user - The name of the currently logged in user

• browser - The browser_id of your browser, if you have browser_mod installed

• hash - Whatever comes after # in the current URL. card-mod watches for location changes through location-changed and popstate events so templates will be rebound with the updated hash

• panel - various information about the panel in view, be it a lovelace dashboard or another panel view. panel is a dictionary containing the following panel attributes with example values shown.

  • panel.fullUrlPath: "card-mod/another-test-view"
  • panel.panelComponentName: "lovelace"
  • panel.panelIcon: "mdi:card-bulleted-outline"
  • panel.panelNarrow: true
  • panel.panelRequireAdmin: false
  • panel.panelTitle: "Card Mod"
  • panel.panelUrlPath: "card-mod"
  • panel.panelTitle: "Card Mod - Test View"
  • panel.viewNarrow: true
  • panel.viewTitle: "Test View"
  • panel.viewUrlPath: "another-test-view"

  You can debug card-mod jinja2 templates by placing the comment {# card_mod.debug #} anywhere in your template. You will see debug messages on template binding, value updated, reuse, unbinding and final ubsubscribing. Any template is kept subscribed in cache for a 20s cooldown period to assist with template application, which can bring a slight speed improvememts when switching back and forth to views, or using the same template on cards on different views.

Home Assistant makes extensive use of something called shadow DOM. This allows for easy reuse of components (such as ha-card or ha-icon) but causes some problems when trying to apply CSS styles to things.

When exploring the cards in your browsers element inspector you may have come across a line that says something like "#shadow-root (open)" (exactly what it says depends on your browser) and have noticed that elements inside that does not inherit the styles from outside.

In order to style elements inside a #shadow-root, you will need to make your style: a dictionary rather than a string.

For each dictionary entry the key will be used to select one or several elements through a modified querySelector() function. The value of the entry will then be injected into those elements.

NOTE: The modified querySelector() function will replace a dollar sign ($) with a #shadow-root in the selector.

The process is recursive, so the value may also be a dictionary. A key of "." (a period) will select the current element.

ha-markdown$

.

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

NOTE: The selector chain of the queue will look for one element at a time separated by spaces or "$".
For each step, only the first match will be selected.
But for the final selector of the chain (i.e. in a given dictionary key) all matching elements will be selected. Chains ending with $ is a special case for convenience, selecting the shadowroots of all elements.

E.g. the following will select the div elements in the first marker on a map card:

"ha-map $ ha-entity-marker $ div": |

But the following will select the div elements in all map markers on a map card (because we end the first key on the ha-entity-marker $ selector and start a new search within each result for div):

"ha-map $ ha-entity-marker $":
  "div": |

NOTE 2: Following on the note above; due to the high level of load order optimization used in Home Assistant, it is not guaranteed that the ha-entity-marker elements exist at the time when card-mod is looking for them. If you break the chain once more:

"ha-map $":
  "ha-entity-marker $":
    "div": |

then card-mod will be able to retry looking from the ha-map $ point at a later time, which may lead to more stable results.

In short; if things seem to be working intermittently - try splitting up the chain into several steps.

card_mod:
  debug: true

Cards that don't have a <ha-element> can still be styled by using the supplied custom:mod-card card.

This is only necessary in very very few instances, and likely to bring more problems than it solves.

Most likely your card contains another card, in which case that is the one you should apply the styles to.

Enough warnings.

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

type: custom:mod-card
card:
  type: custom:beloved-custom-card
  ...
card_mod:
  style: |
    ha-card {
      background: none;
      box-shadow: none;
      border: none;
      transition: none;
    }

Rows in entities conditional rows can be styled directly. If you style the conditional config itself, you need to take care as the conditional row wrapper is not in a shadowRoot so styles may leak to other rows/elements.

type: entities
state_color: true
entities:
  - type: conditional
    conditions:
      - condition: state
        entity: input_boolean.test_boolean
        state: "off"
    row:
      entity: sun.sun
      name: Conditional Sun
      card_mod:
        style: |
          :host {
            color: red;
          }

type: entities
state_color: true
entities:
  - type: conditional
    conditions:
      - condition: state
        entity: input_boolean.test_boolean
        state: "on"
    row:
      entity: sun.sun
      name: Conditional Sun 
    card_mod:
      style:
        hui-simple-entity-row $ hui-generic-entity-row $: |
          .row {
            color: red;
          }

type: entities
state_color: true
entities:
  - type: conditional
    conditions:
      - condition: state
        entity: input_boolean.test_boolean
        state: "on"
    row:
      entity: sun.sun
      name: Conditional Sun
    card_mod:
      style: |
        :host {
          --primary-text-color: red;
        }

The elements in a picture-elements conditional element can be styled directly. If you style the conditional config itself, you need to take care as the conditional element wrapper is not in a shadowRoot so styles may leak to other rows/elements.

type: picture-elements
image:
  media_content_id: https://demo.home-assistant.io/stub_config/t-shirt-promo.png
elements:
  - type: conditional
    conditions:
      - entity: input_boolean.test_boolean
        state: "on"
    elements:
      - type: state-badge
        entity: sun.sun
        style:
          left: 25%
          top: 25%
        card_mod:
          style: |
            :host {
              color: green;
            }

type: picture-elements
image:
  media_content_id: https://demo.home-assistant.io/stub_config/t-shirt-promo.png
elements:
  - type: conditional
    conditions:
      - entity: input_boolean.test_boolean
        state: "on"
    elements:
      - type: state-badge
        entity: sun.sun
        style:
          left: 25%
          top: 25%
    card_mod:
      style:
        hui-state-badge-element $ ha-state-label-badge $: |
          :host {
            color: red;
          }

type: picture-elements
image:
  media_content_id: https://demo.home-assistant.io/stub_config/t-shirt-promo.png
elements:
  - type: conditional
    conditions:
      - entity: input_boolean.test_boolean
        state: "on"
    elements:
      - type: state-badge
        entity: sun.sun
        style:
          left: 25%
          top: 25%
    card_mod:
      style: |
        :host {
          --primary-text-color: purple;
        }

All my test cases are available in the test/views directory.

You can a demo in docker by going to the test directory and running:

docker-compose up

Then going to http://localhost:8125 and logging in with username dev and password dev.

Or you could use the vscode devcontainer and run the task "Run hass".

For details on where card-mod is applied see README-application.

For instructions on how to develop a card-mod theme, see README-themes.md.

For adding card-mods styling powers to your custom card, see README-developers.md.