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.

Liaisons de contexte

uix-<thing>-context-yaml contient une liste YAML de liaisons de contexte structurées pour toute cible UIX. Le guide des contextes UIX présente les ancres, les règles de nom d’entité et des exemples.

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 et uix-dialog-yaml s’appliquent aux styles dont la racine est l’élément du dialogue : ha-dialog, ha-adaptive-dialog ou ha-drawer (les notifications utilisent un dialogue contenant un élément de type drawer). Les dialogues reçoivent aussi la classe type-<dialog-type> ; <dialog-type> correspond au nom de l’élément sans le préfixe ha-. UIX ajoute par exemple type-dialog-box aux boîtes d’alerte et aux dialogues de ce type. Le gestionnaire de dialogues de Home Assistant les place dans la racine Shadow DOM de l’élément <home-assistant> principal. Le dialogue actif en est le dernier enfant : inspectez-le pour déterminer celui à cibler.

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.

Formes YAML et valeurs de repli

Les variables uix-<thing> contiennent du CSS sous forme de chaîne multiligne. Leur variante uix-<thing>-yaml permet une structure YAML avec sélecteurs ; les chaînes commencent par | ou > et leur contenu doit être indenté. Les modèles Jinja peuvent employer les variables configurées et les macros du thème. La variable uix-theme est obligatoire et peut référencer un autre thème pour réutiliser ses styles.

Après activation des thèmes et redémarrage de HA, reload_theme permet de recharger leurs fichiers. Un remplacement local par uix.theme change la référence pour l’élément concerné ; il ne modifie pas le thème global. Les exemples de la référence allemande ci-dessous conservent leurs noms et textes de démonstration.

Exemples complémentaires de la référence allemande

Afficher les configurations complémentaires

Configurations techniques de la référence allemande. Les clés, expressions et valeurs de démonstration restent inchangées ; remplacez les entités par les vôtres.

1. Thème UIX simple

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

2. Thème UIX simple

theme-mods:
  # UIX theme variables, styles and macros

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

3. Thème UIX simple

red-theme:
  uix-theme: red-theme

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

4. Thème UIX simple

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

5. Thème UIX simple

red-theme:
  uix-theme: red-theme

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

6. Thème UIX simple

red-theme:
  uix-theme: red-theme

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

7. Classes

red-theme:
  uix-theme: red-theme

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

8. Parcourir le Shadow DOM

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;
      }

9. Remplacement local de thème avec uix.theme

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

10. Remplacement local de thème avec uix.theme

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

11. Passer de uix-<thing> à uix-<thing>-yaml

red-theme:
  uix-theme: red-theme

  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;
      }

12. Macros

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

13. Macros

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;
        }