Propriétés personnalisées (--*) : variables CSS

Baseline Large disponibilité

Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis avril 2017.

Les noms des propriétés qui sont préfixés par deux tirets (--), comme par exemple --nom-exemple, représentent des propriétés personnalisées (custom properties) qui peuvent contenir une valeur qui pourra être réutilisée dans le document grâce à la fonction var().

La portée des propriétés personnalisées est celle des éléments sur lesquels elles sont déclarées. Ces personnalisées contribuent à la cascade : la valeur utilisée d'une propriété personnalisée sera déterminée par l'algorithme de la cascade.

Valeur initiale	voir le texte
Applicabilité	tous les éléments
Héritée	oui
Valeur calculée	tel que défini avec les variables échangées
Type d'animation	discrète

Syntaxe

css

--some-keyword: left;
--some-color: #123456;
--some-complex-value: 3px 6px rgb(20 32 54);

<declaration-value>: Cette valeur correspond à une séquence de un ou plusieurs fragments tant que la séquence ne contient pas de fragments interdits. Elle représente l'intégralité de ce qu'une déclaration valide peut avoir comme valeur.

Note : Les noms des propriétés personnalisées sont sensibles à la casse — --ma-couleur sera considéré comme une propriété personnalisée distincte de --Ma-Couleur.

Exemples

Exemple simple

HTML

html

<p id="premierParagraphe">
  Ce paragraphe devrait être sur fond bleu avec un texte jaune.
</p>
<p id="secondParagraphe">
  Ce paragraphe devrait être sur fond jaune avec un texte bleu.
</p>
<div id="conteneur">
  <p id="troisiemeParagraphe">
    Ce paragraphe devrait avoir un fond vert et un texte jaune.
  </p>
</div>

CSS

css

:root {
  --premiere-couleur: #1166ff;
  --seconde-couleur: #ffff77;
}

#premierParagraphe {
  background-color: var(--premiere-couleur);
  color: var(--seconde-couleur);
}

#secondParagraphe {
  background-color: var(--seconde-couleur);
  color: var(--premiere-couleur);
}

#conteneur {
  --premiere-couleur: #229900;
}

#troisiemeParagraphe {
  background-color: var(--premiere-couleur);
  color: var(--seconde-couleur);
}

Résultat

Enregistrer les propriétés personnalisées avec `@property`

Dans cet exemple, nous utilisons la règle @property pour enregistrer une propriété personnalisée.

HTML

Notre HTML inclut une liste ordonnée (<ol>) contenant trois éléments de liste (<li>).

html

<ol>
  <li class="one">Élément un</li>
  <li class="two">Élément deux</li>
  <li class="three">Élément trois</li>
</ol>

CSS

Nous utilisons la règle @property pour enregistrer deux propriétés personnalisées.

css

@property --itemSize {
  syntax: "<length> | <percentage>";
  inherits: true;
  initial-value: 200px;
}

@property --borderWidth {
  syntax: "<length>";
  inherits: false;
  initial-value: 10px;
}

Nous essayons de remplacer les valeurs des propriétés personnalisées. Les valeurs définies sur .two sont valides tandis que les valeurs définies sur .three sont invalides.

css

ol {
  --itemSize: 100px;
  --borderWidth: 1px;
}
.two {
  --itemSize: initial;
  --borderWidth: inherit;
}
.three {
  --itemSize: large;
  --borderWidth: 3%;
}

Nous utilisons les deux propriétés personnalisées pour mettre en forme les éléments, en définissant la bordure et la largeur pour tous les éléments en même temps :

css

li {
  width: var(--itemSize);
  border: var(--borderWidth) solid red;
  background-color: yellow;
  margin-bottom: 10px;
}

Résultats

La propriété --itemSize est héritée ; la propriété --borderWidth ne l'est pas. Les propriétés sont définies sur le parent ol, remplaçant les valeurs par défaut définies lors de leur enregistrement. L'élément un hérite de la taille mais pas de la largeur de la bordure de l'OL. Les mots-clés globaux, déclarés pour .two, sont valides pour <length>, donc ils sont utilisés. Les valeurs dans .three sont invalides ("large" n'est pas un <length-percentage> et 3% n'est pas un <length>).