Thèmes

Premiers pas

Pour commencer, activez les thèmes dans Home Assistant.

La méthode recommandée consiste à créer un dossier /config/themes/, puis à ajouter les lignes suivantes à votre fichier configuration.yaml :

frontend:
  themes: !include_dir_merge_named themes/

Après avoir redémarré Home Assistant, placez les fichiers de thème dans ce dossier et chargez-les avec le service Frontend reload_theme.

Les fichiers de thème sont généralement des documents YAML contenant les paramètres des nombreuses variables personnalisables de Home Assistant.

/config/themes/red.yaml

red-theme:
  primary-color: red
  ha-card-border-radius: 20px

Theme name

Le nom du thème doit figurer sur la première ligne ; le reste doit être indenté d'un niveau.

Thème UIX de base

Theme variable

Le thème DOIT définir une variable uix-theme dont la valeur désigne la configuration de thème utilisée par UIX pour ses styles, ses macros et ses polices. En général, uix-theme correspond au nom du thème Home Assistant, mais peut désigner un autre thème si vous souhaitez réutiliser sa configuration UIX.

uix-theme correspondant au thème Home Assistant :

my-awesome-theme:
  uix-theme: my-awesome-theme

  ... UIX theme variables, styles, macros go here ...

uix-theme désignant un autre thème :

theme-mods:
  ... UIX theme variables, styles, macros go here ...

my-awesome-theme:
  uix-theme: theme-mods

/config/themes/red.yaml

red-theme:
  uix-theme: red-theme # this variable must match a valid Home Assistant theme name including case

  primary-color: red
  primary-text-color: white
  ha-card-border-radius: 20

Une fois uix-theme défini, vous pouvez utiliser les fonctionnalités avancées de UIX.

Pour appliquer globalement les fonctions de base de UIX, utilisez les variables uix-<thing>, où <thing> correspond à n'importe quelle variable de thème.

Par exemple, pour ajouter une bordure autour de chaque ligne d'une carte Entités, vous pouvez procéder ainsi :

type: entities
entities:
  - entity: light.bed_light
    style: |
      :host {
        display: block;
        border: 1px solid black;
      }
  - entity: light.ceiling_lights
    uix:
      style: |
        :host {
          display: block;
          border: 1px solid black;
        }
  - entity: light.kitchen_lights
    uix:
      style: |
        :host {
          display: block;
          border: 1px solid black;
        }

Vous pouvez maintenant déplacer cette règle dans le thème :

red-theme:
  uix-theme: red-theme
  ...
  uix-row: |
    :host {
      display: block;
      border: 1px solid black;
    }

uix-<thing> variables

uix-<thing> variables contain strings containing CSS code, and must start with | or > and be indented at least one step.

Comme pour les styles habituels, vous pouvez utiliser les modèles Jinja2 pour traiter les règles.

red-theme:
  uix-theme: red-theme
  ...
  uix-row: |
    :host {
      display: block;
      border: 1px solid {% if is_state(config.entity, 'on') %} red {% else %} black {% endif %};
    }

Classes

UIX lets you set a CSS class to elements. You can then use this in your theme.

red-theme:
  uix-theme: red-theme
  ...
  uix-row: |
    ...
    :host(.teal) {
      background: teal;
    }
    :host(.purple) {
      background: purple;
    }

type: entities
entities:
  - entity: light.bed_light
  - entity: light.ceiling_lights
    uix:
      class: teal
  - entity: light.kitchen_lights
    uix:
      class: purple

Naviguer dans le DOM shadow

Comme pour les styles UIX appliqués à une carte, vous pouvez parcourir la structure DOM fantôme de l'élément à styliser. Pour cela, indiquez la variable uix-<thing>-yaml ; la syntaxe reste identique.

red-theme:
  uix-theme: red-theme
  ...
  uix-row-yaml: |
    ...
    hui-generic-entity-row $ state-badge $: |
      @keyframes pulse {
        50% {
          opacity: 0.5;
        }
      }
      ha-state-icon {
        animation: pulse 2s infinite;
      }

Theme variables MUST be strings

Bien que la valeur de uix-<thing>-yaml soit du YAML, elle DOIT être une chaîne du point de vue du thème, contenant elle-même d'autres chaînes.

Surcharge locale de thème avec uix.theme

Vous pouvez imposer à une carte, une ligne, un badge ou un élément stylisé un thème Home Assistant différent du thème global actif. Pour ce nœud UIX, uix.theme est prioritaire sur le thème hérité ou actif.

Thème principal de ligne rouge :

row-red:
  uix-theme: row-red
  uix-row-yaml: |
    hui-generic-entity-row $: |
      .info{
        color: red;
      }

Thème de remplacement de ligne bleue :

row-blue-override:
  uix-theme: row-blue-override
  uix-row-yaml: |
    hui-generic-entity-row $: |
      .info{
        color: blue;
      }

Carte Entités avec un thème de remplacement pour une ligne :

type: entities
title: Lights
entities:
  - entity: light.bed_light
  - entity: light.ceiling_lights
  - entity: light.kitchen_lights
    uix:
      theme: row-blue-override

Take caution where you use theme overrides

La personnalisation des styles et des thèmes dans Home Assistant peut devenir complexe. Une variable CSS peut ne pas s'appliquer comme prévu. Par exemple, si vous définissez --primary-text-color: color; sur une ligne Entités avec un style UIX direct sur :host {} ou avec uix.theme, vous pourriez vous attendre à ce que le texte prenne cette couleur. Toutefois, dans ce cas, la propriété color est définie sur l'élément ha-card de la carte Entités ; le remplacement n'aura donc aucun effet.

Mettre à jour une variable uix-<thing> vers uix-<thing>-yaml

UIX theme variable precedence

uix-<thing>-yaml always takes precedence over uix-<thing> which is NOT used if uix-<thing>-yaml is present in the theme.

En développant vos thèmes UIX, vous pourriez commencer avec des chaînes CSS simples dans uix-<thing>, puis avoir besoin de passer à uix-<thing>-yaml. Utilisez alors le sélecteur YAML racine .:. Voici l'exemple complet du thème rouge avec uix-row-yaml.

red-theme:
  uix-theme: red-theme # this variable must match a valid Home Assistant theme name including case

  primary-color: red
  ha-card-border-radius: 20px

  uix-row-yaml: |
    .: |
      :host {
        display: block;
        border: 1px solid {% if is_state(config.entity, 'on') %} red {% else %} black {% endif %};
      }
      :host(.teal) {
        background: teal;
      }
      :host(.purple) {
        background: purple;
      }
    hui-generic-entity-row $ state-badge $: |
      @keyframes pulse {
        50% {
          opacity: 0.5;
        }
      }
      ha-state-icon {
        animation: pulse 2s infinite;
      }

Variables de thème

• uix-card
• uix-row
• uix-glance
• uix-badge
• uix-heading-badge
• uix-assist-chip
• uix-element
• uix-entity-marker
• uix-root
• uix-view
• uix-more-info
• uix-sidebar
• uix-config
• uix-panel-custom
• uix-top-app-bar-fixed
• uix-dialog
• uix-toast
• uix-grid-section
• uix-calendar
• uix-todo
• uix-history
• uix-states-history-charts
• uix-drawer
• uix-view-background
• uix-persistent-notification-item

Aussi <any variable>-yaml.

Polices

uix-fonts charge des polices web lorsqu'un thème global est sélectionné. UIX crée des objets FontFace et les enregistre dans document.fonts. Les composants Home Assistant peuvent les utiliser, y compris dans les shadow roots. Cette option charge uniquement les polices ; les variables de thème ou les styles UIX déterminent leur utilisation.

Les valeurs des thèmes Home Assistant doivent être des chaînes. Placez la définition dans un bloc | :

retro-theme:
  uix-theme: retro-theme
  uix-fonts: |
    ChicagoFLF:
      source: url("https://cdn.jsdelivr.net/npm/@sakun/system.css@0.1.11/fonts/ChicagoFLF.woff2") format("woff2")
    dashboard-regular:
      family: My Dashboard Font
      source: url("/local/fonts/dashboard-regular.woff2") format("woff2")
      descriptors:
        weight: "400"
        style: normal
        display: swap
    dashboard-bold:
      family: My Dashboard Font
      source: url("/local/fonts/dashboard-bold.woff2") format("woff2")
      descriptors:
        weight: "700"

  ha-font-family-body: '"ChicagoFLF", sans-serif'
  ha-font-family-heading: '"ChicagoFLF", sans-serif'
  uix-card: |
    ha-card {
      font-family: "ChicagoFLF", sans-serif;
    }

Clé	Obligatoire	Description
family	Non	Famille CSS ; par défaut, la clé de l'entrée. Plusieurs variantes peuvent partager la même famille.
source	Oui	Source CSS, par exemple url("/local/fonts/example.woff2") format("woff2"). Accepte des alternatives séparées par des virgules et local("Font Name"). Utilisez des fichiers de police, pas l'URL d'une feuille CSS du fournisseur.
descriptors	Non	Descripteurs FontFace avec leurs noms JavaScript : weight, style, stretch, display, unicodeRange, featureSettings, variationSettings, ascentOverride, descentOverride, lineGapOverride. Les valeurs sont des chaînes ; weight accepte aussi un nombre.

Utilisez une entrée distincte pour chaque graisse ou style. Une police variable peut définir une plage comme weight: "100 900". Les fichiers de /config/www/fonts/ sont servis sous /local/fonts/. Les serveurs distants doivent autoriser les requêtes inter-origines. Les descripteurs correspondent à l'API FontFace ; la prise en charge de variationSettings, ascentOverride, descentOverride et lineGapOverride varie, Safari pouvant ignorer certaines valeurs.

Les polices suivent le thème global Home Assistant, y compris modes.light et modes.dark. Le uix-fonts d'un mode remplace la définition de base ; uix-fonts: "{}" indique un mode sans police personnalisée. Si uix-theme désigne un autre thème, UIX utilise sa définition de polices. Les anciennes références card-mod-theme sont prises en charge. Un thème sélectionné uniquement pour une vue, une carte ou via uix.theme ne charge pas ses polices.

UIX lance les téléchargements sans retarder les styles et n'enregistre qu'une fois les entrées identiques. Un changement ou rechargement de thème supprime les enregistrements UIX inutiles, y compris les polices en cours de chargement. Les polices de Home Assistant et des autres intégrations sont conservées. Les entrées invalides et échecs de téléchargement produisent des avertissements dans la console sans bloquer les autres polices ou styles. Rechargez les thèmes pour réessayer les téléchargements échoués.

uix-fonts accepte une définition YAML statique sans modèles. Il n'insère ni CSS ni éléments <style> dans l'en-tête du document.

Boîtes de dialogue

uix-dialog and uix-dialog-yaml apply to styles rooted in the dialog element of dialogs which may be ha-dialog, ha-adaptive-dialog, or ha-drawer (notification uses a dialog with an element using the drawer type). Dialogs will also have their class set to type-<dialog-type> where <dialog-type> will be the dialog element name with any ha- prefix stripped. e.g. UIX will append type-dialog-box to dialog boxes as used by alerts and other dialog boxes. The Home Assistant dialog manager places dialogs in the shadow root of the top <home-assistant> element. The active dialog will be the last child of the shadow root. To view what dialog you wish to target, review the last child of this shadow root node.

Consultez le guide UIX Styliser les boîtes de dialogue avec UI eXtension.

Macros

Les thèmes peuvent définir des macros Jinja2 réutilisables par toutes les cartes qui les utilisent. Les macros sont déclarées sous la clé de thème uix-macros-yaml, sous forme de dictionnaire YAML de définitions. Consultez Modèles - Macros pour la référence complète de configuration.

my-awesome-theme:
  uix-theme: my-awesome-theme

  uix-macros-yaml: |
    is_on:
      params:
        - entity_id
      returns: true
      template: "{%- do returns(is_state(entity_id, 'on')) -%}"
    badge_color:
      params:
        - entity_id
        - name: color_on
          default: "'var(--state-active-color)'"
        - name: color_off
          default: "'var(--state-inactive-color)'"
      template: "{{ color_on if is_on(entity_id) else color_off }}"

Exemple de badge utilisant les valeurs par défaut de la macro de thème badge_color() :

  badges:
    - type: entity
      entity: light.bed_light
      tap_action:
        action: toggle
      uix:
        style: |
          ha-badge {
            --badge-color: {{ badge_color(config.entity) }} !important;
          }

Exemple de badge définissant la variable nommée color_on sur red dans la macro de thème badge_color() :

  badges:
    - type: entity
      entity: light.bed_light
      tap_action:
        action: toggle
      uix:
        style: |
          ha-badge {
            --badge-color: {{ badge_color(config.entity, color_on='red') }} !important;
          }

Les macros uix.macros définies sur une carte sont prioritaires sur celles du thème portant le même nom.

WARNING

Theme macros are only available in UIX styling templates, not in UIX Forge element/forge templates. Utilisez les fonderies globales de UIX Forge pour définir des forge.macros disponibles globalement ou pour un mold.