var()
Baseline
Widely available
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.
La fonction CSS var() permet d'insérer la valeur d'une propriété personnalisée (parfois appelée « variable CSS ») à la place de n'importe quelle partie de la valeur d'une autre propriété.
Exemple interactif
border-color: var(--color-a);
border-color: var(--color-b);
border-color: var(--color-c);
<section class="default-example" id="default-example">
<div id="example-element">
Trois options de couleur ont été définies sur :root utilisez-les pour
changer la couleur de la bordure.
</div>
</section>
:root {
--color-a: pink;
--color-b: green;
--color-c: rebeccapurple;
}
#example-element {
border: 10px solid black;
padding: 10px;
}
La fonction var() ne peut pas être utilisée dans les noms de propriétés, les sélecteurs ou tout autre endroit en dehors des valeurs de propriétés. (Cela produit généralement une syntaxe invalide, ou bien une valeur dont la signification n'a aucun rapport avec la variable.)
Syntaxe
/* Utilisation simple */
var(--custom-prop);
/* Avec valeur de repli */
var(--custom-prop,); /* valeur vide comme repli */
var(--custom-prop, initial); /* valeur initiale de la propriété comme repli */
var(--custom-prop, red);
var(--custom-prop, var(--default-value));
var(--custom-prop, var(--default-value, red));
Le premier argument de la fonction est le nom de la propriété personnalisée à substituer. Un second argument optionnel sert de valeur de repli. Si la propriété personnalisée référencée par le premier argument n'est pas définie ou vaut un mot-clé global CSS, la fonction utilise la seconde valeur.
La syntaxe de la valeur de repli, comme celle des propriétés personnalisées, autorise les virgules. Par exemple, var(--foo, red, blue) définit une valeur de repli de red, blue ; tout ce qui se trouve entre la première virgule et la fin de la fonction est considéré comme valeur de repli.
Valeurs
<custom-property-name>-
Nom d'une propriété personnalisée représenté par un identifiant commençant par deux tirets. Les propriétés personnalisées sont uniquement destinées aux auteur·ice·s et utilisateur·ice·s ; CSS ne leur attribuera jamais de signification autre que celle présentée ici.
<declaration-value>-
La valeur de repli de la propriété personnalisée, utilisée si la propriété personnalisée n'est pas définie ou vaut un mot-clé global CSS. Cette valeur peut contenir n'importe quel caractère sauf certains caractères avec une signification spéciale comme les retours à la ligne, les crochets fermants non appariés, c'est-à-dire
),], ou}, les points-virgules de premier niveau, ou les points d'exclamation. La valeur de repli peut elle-même être une propriété personnalisée utilisant la syntaxevar(). Si la valeur de repli est omise, et que la propriété personnalisée n'est pas définie, la fonctionvar()donne une valeur invalide.Note :
var(--a,)est valide, ce qui définit que si la propriété personnalisée--an'est pas définie ou vaut un mot-clé global CSS, la fonctionvar()doit être remplacée par rien.
Syntaxe formelle
<var()> =
var( <custom-property-name> , <declaration-value>? )
Exemples
Utiliser une propriété personnalisée définie sur :root
CSS
:root {
--main-bg-color: pink;
}
body {
background-color: var(--main-bg-color);
}
Résultat
Ici, la valeur de la propriété background-color a été définie via la propriété personnalisée --main-bg-color. Ainsi, la couleur de fond du corps HTML sera rose.
Utiliser une propriété personnalisée avant qu'elle ne soit définie
CSS
body {
background-color: var(--main-bg-color);
}
:root {
--main-bg-color: pink;
}
Résultat
Dans cet exemple, la couleur de fond du corps HTML sera rose même si la propriété personnalisée est définie plus loin.
Utiliser une propriété personnalisée définie dans un autre fichier
HTML
<!doctype html>
<html lang="fr">
<head>
<meta charset="utf-8" />
<link rel="stylesheet" href="1.css" />
<link rel="stylesheet" href="2.css" />
</head>
<body></body>
</html>
CSS
/* 1.css */
body {
background-color: var(--main-bg-color);
}
/* 2.css */
:root {
--main-bg-color: pink;
}
Résultat
La couleur de fond du corps HTML sera rose dans ce cas, même si la propriété personnalisée est déclarée dans un autre fichier.
Propriétés personnalisées avec valeurs de repli pour le cas où la propriété n'est pas définie
HTML
<div class="component">
<h1 class="header">En-tête</h1>
<p class="text">Texte</p>
</div>
CSS
/* Dans le style du composant : */
.component .header {
/* header-color n'est pas définie, donc reste bleue, la valeur de repli */
color: var(--header-color, blue);
}
.component .text {
color: var(--text-color, black);
}
/* Dans le style de l'application principale : */
.component {
--text-color: #008800;
}
Résultat
Comme --header-color n'est pas définie, le texte « En-tête » sera bleu, la valeur de repli.
Utiliser une propriété personnalisée comme valeur de repli
CSS
:root {
--backup-bg-color: teal;
}
body {
background-color: var(--main-bg-color, var(--backup-bg-color, white));
}
Résultat
Comme --main-bg-color n'est pas définie, la propriété background-color du corps prendra la valeur de repli --backup-bg-color, qui est sarcelle.
Valeurs invalides
Les fonctions var() peuvent donner des valeurs invalides si :
- La propriété personnalisée n'est pas définie et aucune valeur de repli n'est fournie.
- La propriété personnalisée est définie mais sa valeur est invalide pour la propriété dans laquelle elle est utilisée.
Dans ce cas, la propriété est traitée comme si elle avait la valeur unset. Les variables ne peuvent pas « échouer tôt » comme d'autres erreurs de syntaxe, donc lorsque l'agent utilisateur réalise qu'une valeur de propriété est invalide, il a déjà ignoré les autres valeurs issues de la cascade.
Par exemple :
HTML
<p class="p1">Variable non définie</p>
<p class="p2">Variable invalide</p>
<p class="p3">Couleur littérale invalide</p>
CSS
p {
color: red;
}
.p1 {
color: var(--invalid-color);
}
.p2 {
--invalid-color: 20px;
color: var(--invalid-color);
}
.p3 {
color: 20px;
}
Résultat
Remarquez que les paragraphes utilisant var() sont réinitialisés à la couleur noire par défaut, mais que le paragraphe avec une couleur littérale invalide reste rouge, car la déclaration color: 20px est simplement ignorée.
Spécifications
| Specification |
|---|
| CSS Custom Properties for Cascading Variables Module Level 1 # using-variables |
Compatibilité des navigateurs
Voir aussi
env(…)— variables d'environnement en lecture seule contrôlées par l'agent utilisateur.- Utiliser les propriétés personnalisées CSS (variables)
- La règle
@property - Le module des propriétés personnalisées CSS pour les variables en cascade module