Utiliser des propriétés personnalisées CSS (variables)

Déclarer des propriétés personnalisées

En CSS, vous pouvez déclarer une propriété personnalisée en utilisant deux tirets comme préfixe pour le nom de la propriété, ou en utilisant la règle @property. Les sections suivantes décrivent comment utiliser ces deux méthodes.

Utiliser un préfixe de deux tirets (--)

Une propriété personnalisée préfixée par deux tirets commence par --, suivie du nom de la propriété (par exemple, --ma-propriete), et d'une valeur de propriété qui peut être n'importe quelle valeur CSS valide. Comme toute autre propriété, elle est écrite à l'intérieur d'un ensemble de règles. L'exemple suivant montre comment créer une propriété personnalisée --couleur-principale-fond et utilise une valeur de couleur nommée (<named-color>) brown :

section {
  --couleur-principale-fond: brown;
}

Le sélecteur donné à l'ensemble de règles (<section>) dans l'exemple ci-dessus) définit la portée dans laquelle la propriété personnalisée peut être utilisée. Pour cette raison, une pratique courante consiste à définir les propriétés personnalisées sur la pseudo-classe :root, afin qu'elles puissent être référencées globalement :

:root {
  --couleur-principale-fond: brown;
}

Ce n'est pas toujours le cas : vous pouvez avoir une bonne raison de limiter la portée de vos propriétés personnalisées.

Utiliser la règle @property

La règle @property permet d'être plus expressif dans la définition d'une propriété personnalisée en offrant la possibilité d'associer un type à la propriété, de définir des valeurs par défaut et de contrôler l'héritage. L'exemple suivant crée une propriété personnalisée appelée --couleur-logo qui attend une couleur (<color>) :

@property --couleur-logo {
  syntax: "<color>";
  inherits: false;
  initial-value: #c0ffee;
}

Si vous souhaitez définir ou travailler avec des propriétés personnalisées en JavaScript plutôt que directement en CSS, il existe une API correspondante à cet effet. Vous pouvez en savoir plus sur son fonctionnement sur la page de l'API des propriétés et valeurs CSS.

Référencer les propriétés personnalisées avec var()

Quelle que soit la méthode choisie pour définir une propriété personnalisée, vous les utilisez en référencant la propriété dans une fonction var() à la place d'une valeur de propriété standard :

details {
  background-color: var(--couleur-principale-fond);
}

Premiers pas avec les propriétés personnalisées

Commençons par un peu de HTML sur lequel nous aimerions appliquer des styles. Il y a un <div> qui agit comme un conteneur et qui inclut quelques éléments enfants, certains avec des éléments imbriqués :

<div class="conteneur">
  <div class="un">
    <p>Un</p>
  </div>
  <div class="deux">
    <p>Deux</p>
    <div class="trois">
      <p>Trois</p>
    </div>
  </div>
  <input class="quatre" placeholder="Quatre" />
  <textarea class="cinq">Cinq</textarea>
</div>

Nous allons utiliser le CSS suivant pour mettre en forme quelques éléments différents en fonction de leurs classes (certaines règles de mise en page ne sont pas affichées ci-dessous afin que nous puissions nous concentrer sur les couleurs). En fonction de leurs classes, nous donnons aux éléments des couleurs de fond teal ou pink :

/* Définir les polices, les bordures et les marges */
body,
textarea,
::placeholder {
  font-family: sans-serif;
  color: white;
}

div,
input,
textarea {
  border: 2px black solid;
  padding: 4px;
  margin: 4px;
}

.conteneur {
  display: grid;
  gap: 10px;
}

/* Pour chaque classe, définir des couleurs */
.un {
  background-color: teal;
}

.deux {
  color: black;
  background-color: pink;
}

.trois {
  color: white;
  background-color: teal;
}

.quatre {
  background-color: teal;
}

.cinq {
  background-color: teal;
}

Ça produit le résultat suivant :

Il y a une opportunité d'utiliser des propriétés personnalisées pour remplacer les valeurs répétitives dans ces règles. Après avoir défini --couleur-principale-fond dans la portée de .conteneur et référencé sa valeur à plusieurs endroits, les styles mis à jour ressemblent à ceci :

/* Définir --couleur-principale-fond ici */
.conteneur {
  --couleur-principale-fond: teal;
}

/* Pour chaque classe, définir des couleurs */
.un {
  background-color: var(--couleur-principale-fond);
}

.deux {
  color: black;
  background-color: pink;
}

.trois {
  color: white;
  background-color: var(--couleur-principale-fond);
}

.quatre {
  background-color: var(--couleur-principale-fond);
}

.cinq {
  background-color: var(--couleur-principale-fond);
}

Utiliser la pseudo-classe :root

Pour certaines déclarations CSS, il est possible de les déclarer plus haut dans la cascade et de laisser l'héritage CSS résoudre ce problème. Pour des projets non triviaux, ce n'est pas toujours possible. En déclarant une propriété personnalisée sur la pseudo-classe :root et en l'utilisant là où elle est nécessaire dans tout le document, un·e auteur·ice CSS peut réduire le besoin de répétition :

/* Définir --couleur-principale-fond ici */
:root {
  --couleur-principale-fond: teal;
}

/* Pour chaque classe, définir des couleurs */
.un,
.trois,
.quatre,
.cinq {
  background-color: var(--couleur-principale-fond);
}

.deux {
  color: black;
  background-color: pink;
}

Cela conduit au même résultat que l'exemple précédent, mais permet d'avoir une déclaration canonique de la valeur de la propriété souhaitée (--couleur-principale-fond: teal;), ce qui est très utile si vous souhaitez modifier la valeur dans l'ensemble du projet plus tard.

Héritage des propriétés personnalisées

Une propriété personnalisée définie en utilisant deux tirets -- au lieu de @property hérite toujours de la valeur de son parent. C'est démontré dans l'exemple suivant :

<div class="un">
  <p>Un</p>
  <div class="deux">
    <p>Deux</p>
    <div class="trois"><p>Trois</p></div>
    <div class="quatre"><p>Quatre</p></div>
  </div>
</div>

div {
  color: black;
  font-family: sans-serif;
  width: 75%;
  height: 80%;
  margin: 4px;
  border: 2px black solid;
  display: inline-block;
}

p {
  margin: 0;
}

.un {
  height: 250px;
}

.deux {
  color: white;
  height: 80%;
}

.trois {
  color: black;
  height: 40%;
}

.quatre {
  color: white;
  height: 40%;
}

div {
  background-color: var(--couleur-boite);
}

.deux {
  --couleur-boite: teal;
}

.trois {
  --couleur-boite: pink;
}

Les résultats de var(--couleur-boite) en fonction de l'héritage sont les suivants :

• class="un" : valeur invalide, c'est la valeur par défaut d'une propriété personnalisée définie de cette manière
• class="deux" : teal
• class="trois" : pink
• class="quatre" : teal (hérité de son parent)

Un aspect des propriétés personnalisées que les exemples ci-dessus démontrent est qu'elles ne se comportent pas exactement comme des variables dans d'autres langages de programmation. La valeur est calculée là où elle est nécessaire, et non stockée et réutilisée dans d'autres parties d'une feuille de style. Par exemple, vous ne pouvez pas définir la valeur d'une propriété et vous attendre à récupérer cette valeur dans la règle d'un descendant d'un frère. La propriété n'est définie que pour le sélecteur correspondant et ses descendants.

Utiliser @property pour contrôler l'héritage

La règle @property permet de définir explicitement si la propriété hérite ou non. L'exemple suivant crée une propriété personnalisée en utilisant la règle @property. L'héritage est désactivé, un type de données <color> est défini, et une valeur initiale de teal est définie.

L'élément parent définit --couleur-boite à une valeur de green et utilise --couleur-boite comme valeur pour sa couleur de fond. L'élément enfant utilise également background-color: var(--couleur-boite), et nous nous attendrions à ce qu'il ait la couleur green si l'héritage était activé (ou si elle était définie en utilisant la syntaxe à double tiret).

<div class="parent">
  <p>Élément parent</p>
  <div class="enfant">
    <p>Élément enfant avec l'héritage désactivé pour --couleur-boite.</p>
  </div>
</div>

div {
  color: white;
  font-family: sans-serif;
  width: 200px;
  height: 200px;
  margin: 4px;
  padding: 8px;
  border: 2px black solid;
  display: inline-block;
}

@property --couleur-boite {
  syntax: "<color>";
  inherits: false;
  initial-value: teal;
}

.parent {
  --couleur-boite: green;
  background-color: var(--couleur-boite);
}

.enfant {
  width: 80%;
  height: 40%;
  background-color: var(--couleur-boite);
}

Parce que inherits: false; est défini dans la règle @property, et qu'une valeur pour la propriété --couleur-boite n'est pas déclarée dans la portée de .enfant, la valeur initiale de teal est utilisée à la place de green qui aurait été héritée du parent :

Valeurs de repli pour les propriétés personnalisées

Vous pouvez définir des valeurs de repli pour les propriétés personnalisées en utilisant la fonction var() et la valeur initiale de la règle @property.

Définir des valeurs de repli dans la fonction var()

En utilisant la fonction var(), vous pouvez définir plusieurs valeurs de repli lorsque la variable donnée n'est pas encore définie ; cela peut être utile lors de l'utilisation de éléments personnalisés et de DOM d'ombre.

Le premier argument de la fonction est le nom de la propriété personnalisée. Le deuxième argument de la fonction est une valeur de repli optionnelle, qui est utilisée comme valeur de substitution lorsque la propriété personnalisée référencée est invalide. La fonction accepte deux paramètres, en assignant tout ce qui suit la première virgule comme deuxième paramètre. Si le deuxième paramètre est invalide, le repli échoue. Par exemple :

.un {
  /* Rouge si --ma-variable n'est pas définie */
  color: var(--ma-variable, red);
}

.deux {
  /* rose si --ma-variable et --mon-fond ne sont pas définies */
  color: var(--ma-variable, var(--mon-fond, pink));
}

.trois {
  /* Invalide : "--mon-fond, pink" */
  color: var(--ma-variable, --mon-fond, pink);
}

Inclure une propriété personnalisée comme valeur de repli, comme dans le deuxième exemple ci-dessus (var(--ma-variable, var(--mon-fond, pink))), est la bonne façon de fournir plus d'une valeur de repli avec var(). Vous devez toutefois être conscient de l'impact sur les performances de cette méthode, car il faut plus de temps pour analyser les variables imbriquées.

Valeurs de repli utilisant la valeur initiale de @property

En dehors de l'utilisation de var(), la valeur initiale définie dans la règle @property peut être utilisée comme mécanisme de repli. En fait, nous avons déjà vu cela dans la section héritage de @property.

L'exemple suivant définit une valeur initiale de --couleur-boite à teal en utilisant la règle @property. Dans le jeu de règles suivant la règle @property, nous voulons définir --couleur-boite à pink, mais il y a une faute de frappe dans le nom de la valeur. Il en va de même pour le troisième <div> où nous avons utilisé 2rem pour la propriété personnalisée qui attend une valeur valide de <color>. Les valeurs 2rem et peenk sont toutes deux des valeurs de couleur invalides, donc la valeur initiale de teal est appliquée :

@property --couleur-boite {
  syntax: "<color>";
  initial-value: teal;
  inherits: false;
}

.un {
  --couleur-boite: pink;
  background-color: var(--couleur-boite);
}

.deux {
  --couleur-boite: peenk;
  background-color: var(--couleur-boite);
}

.trois {
  --couleur-boite: 2rem;
  background-color: var(--couleur-boite);
}

div {
  color: white;
  font-family: sans-serif;
  width: 100px;
  height: 100px;
  margin: 4px;
  padding: 8px;
  border: 2px black solid;
  display: inline-block;
}

.un {
  color: black;
}

<div class="un">
  <p>Un</p>
</div>
<div class="deux">
  <p>Deux.</p>
</div>
<div class="trois">
  <p>Trois.</p>
</div>

Propriétés personnalisées invalides

Chaque propriété CSS peut se voir attribuer un ensemble de valeurs défini. Si vous essayez d'attribuer une valeur à une propriété qui est en dehors de son ensemble de valeurs valides, elle est considérée comme invalide.

Lorsque le navigateur rencontre une valeur invalide pour une propriété CSS normale (par exemple, une valeur de 16px pour la propriété color), il ignore la déclaration, et les éléments se voient attribuer les valeurs qu'ils auraient eues si la déclaration n'existait pas. Dans l'exemple suivant, nous voyons ce qui se passe lorsqu'une déclaration CSS normale est invalide ; color: 16px; est ignoré et la règle précédente color: blue est appliquée à la place :

<p>Ce paragraphe est initialement en noir.</p>

p {
  font-weight: bold;
  color: blue;
}

p {
  /* oups, c'est pas une couleur valide */
  color: 16px;
}

Cependant, lorsque les valeurs des propriétés personnalisées sont analysées, le navigateur ne sait pas encore où elles sont utilisées, il doit donc considérer presque toutes les valeurs comme valides. Malheureusement, ces valeurs valides peuvent être utilisées, avec la notation fonctionnelle var(), dans un contexte où elles pourraient ne pas avoir de sens. Les propriétés et les variables personnalisées peuvent conduire à des déclarations CSS invalides, ce qui conduit au concept de valide au moment du calcul.

Lorsque le navigateur rencontre une substitution var() invalide, la valeur initiale ou héritée de la propriété est utilisée. Cet exemple est similaire au précédent, sauf que nous utilisons une propriété personnalisée.

Le navigateur remplace la valeur de --couleur-texte à la place de var(--couleur-texte), mais 16px n'est pas une valeur de propriété valide pour color. Après substitution, la propriété n'a pas de sens, donc le navigateur gère cette situation en deux étapes :

1. Vérifiez si la propriété color est héritée. Elle l'est, mais ce <p> n'a aucun parent avec la propriété color définie. Nous passons donc à l'étape suivante.
2. Définissez la valeur sur sa valeur initiale par défaut, qui est le noir.

<p>Ce paragraphe est initialement en noir.</p>

:root {
  --couleur-texte: 16px;
}

p {
  font-weight: bold;
  color: blue;
}

p {
  color: var(--couleur-texte);
}

Pour de tels cas, la règle @property peut prévenir des résultats inattendus en permettant de définir la valeur initiale de la propriété :

<p>Ce paragraphe est initialement en noir.</p>

@property --couleur-texte {
  syntax: "<color>";
  inherits: false;
  initial-value: teal;
}

:root {
  --couleur-texte: 16px;
}

p {
  font-weight: bold;
  color: blue;
}

p {
  color: var(--couleur-texte);
}

Valeurs en JavaScript

Pour utiliser les valeurs des propriétés personnalisées en JavaScript, c'est comme pour les propriétés standard.

// obtenir la variable depuis le style embarqué
element.style.getPropertyValue("--ma-variable");

// obtenir la variable depuis n'importe où
getComputedStyle(element).getPropertyValue("--ma-variable");

// définir la variable dans le style embarqué
element.style.setProperty("--ma-variable", jsVar + 4);

Voir aussi

• La règle @property
• La fonction var()
• Le module des propriétés pour les variables de la cascade CSS
• Syntaxe des propriétés personnalisées
• L'API des propriétés et valeurs CSS