Docs CSS exécutables : Variables CSS

Q: Qu'est-ce que :root en CSS ?

:root est une pseudo-classe qui cible l'élément racine du document, dans une page HTML. Les variables déclarées là sont héritées par tous les éléments. Elle a la spécificité d'une classe, donc elle l'emporte sur un simple sélecteur html.

Q: Comment définir une valeur par défaut pour une variable CSS ?

Passez un second argument à var() : color: var(--accent, #2563eb);. La valeur de secours sert quand --accent n'est défini ni sur l'élément ni sur ses ancêtres. Elle ne sert pas quand la variable est définie avec une valeur invalide pour la propriété.

Q: Comment modifier une variable CSS avec JavaScript ?

Appelez setProperty sur le style d'un élément : document.documentElement.style.setProperty('--brand', '#16a34a'). Toutes les règles qui utilisent var(--brand) se mettent à jour d'un coup. Lisez la valeur actuelle avec getComputedStyle(el).getPropertyValue('--brand').

Q: Les noms de variables CSS sont-ils sensibles à la casse ?

Oui. --Brand et --brand sont deux variables différentes, contrairement aux noms de propriétés ordinaires comme color, qui ne sont pas sensibles à la casse.

Déclarer et utiliser une variable CSS

Une variable CSS, officiellement une propriété personnalisée, est une propriété dont le nom commence par --. Déclarez-la une fois, en général sur :root pour que toute la page en hérite, et lisez-la n'importe où avec var().

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>CSS variables</title>
  <style>
    :root {
      --brand: #2563eb;
      --radius: 8px;
      --space: 12px;
    }

    .btn {
      background: var(--brand);
      color: white;
      border: 0;
      border-radius: var(--radius);
      padding: var(--space) calc(var(--space) * 2);
    }

    .card {
      border: 2px solid var(--brand);
      border-radius: var(--radius);
      padding: var(--space);
      margin-bottom: var(--space);
    }
  </style>
</head>
<body>
  <div class="card">Change --brand in :root and both change.</div>
  <button class="btn">Button</button>
</body>
</html>

Remplacez --brand par #16a34a et la bordure de la carte et le bouton changent ensemble. Tout l'intérêt est là : une valeur, un seul endroit à modifier. Les variables se combinent aussi avec calc(), comme le montre le padding latéral du bouton.

Syntaxe

:root {
  --name: value;         /* declare */
}

.element {
  color: var(--name);                 /* use */
  color: var(--name, #111827);        /* use, with a fallback */
  padding: calc(var(--space) * 2);    /* compute with it */
}

Règle	Détail
Nom	Commence par `--`, suivi de lettres, chiffres, `-` ou `_`. Sensible à la casse : `--Brand` n'est pas `--brand`.
Valeur	Presque n'importe quoi : une couleur, une longueur, une liste, une chaîne. Elle n'est vérifiée qu'au moment de son utilisation.
Où la déclarer	Dans n'importe quelle règle. `:root` pour les valeurs globales, le sélecteur d'un composant pour les valeurs locales.
Héritage	Les propriétés personnalisées s'héritent, un enfant voit donc les valeurs de ses ancêtres.
Où `var()` fonctionne	Uniquement dans les valeurs de propriétés, pas dans les sélecteurs, les noms de propriétés ni les conditions `@media`.

:root cible l'élément <html>. On l'utilise à la place de html parce qu'il a la spécificité d'une classe et que, par convention, il signale des « réglages globaux ».

Portée : surcharger une variable par composant

Comme les variables s'héritent, redéclarer une variable sur un élément la modifie pour cet élément et tout ce qu'il contient. La règle qui utilise la variable ne change pas.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Scope</title>
  <style>
    :root { --accent: #2563eb; }

    .alert {
      border-inline-start: 6px solid var(--accent);
      background: #e5e7eb;
      color: #111827;
      padding: 10px 14px;
      margin-bottom: 8px;
    }

    .alert.success { --accent: #16a34a; }
    .alert.warning { --accent: #f59e0b; }
  </style>
</head>
<body>
  <div class="alert">Info uses the global blue.</div>
  <div class="alert success">Success overrides --accent.</div>
  <div class="alert warning">Warning overrides it too.</div>
</body>
</html>

Les variantes ne définissent qu'une variable, jamais la bordure elle-même. Ajouter une quatrième variante tient en une ligne.

Valeurs de secours

var(--name, fallback) utilise la valeur de secours quand la variable n'est définie ni sur l'élément ni sur un ancêtre. Tout ce qui suit la première virgule forme la valeur de secours, qui peut donc elle-même contenir des virgules (var(--font, Georgia, serif)) et peut être un autre var().

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Fallback</title>
  <style>
    p { padding: 8px; color: white; }
    .a { background: var(--missing, #16a34a); }
    .b { --defined: #2563eb; background: var(--defined, #16a34a); }
    .c { background: var(--missing, var(--also-missing, #f59e0b)); }
  </style>
</head>
<body>
  <p class="a">Green: --missing is not defined, fallback used.</p>
  <p class="b">Blue: --defined exists, fallback ignored.</p>
  <p class="c">Amber: nested fallback.</p>
</body>
</html>

Modifier des variables avec JavaScript : un changement de thème

JavaScript peut définir une variable sur n'importe quel élément avec style.setProperty(). Définissez-la sur document.documentElement (l'élément <html>) et toute la page suit. Le schéma le plus courant bascule une classe qui redéfinit les variables :

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Theme</title>
  <style>
    :root {
      --bg: #ffffff;
      --text: #111827;
      --muted: #e5e7eb;
    }
    .dark {
      --bg: #111827;
      --text: #f9fafb;
      --muted: #374151;
    }
    body { background: var(--bg); color: var(--text); padding: 12px; }
    .panel { background: var(--muted); padding: 12px; border-radius: 8px; }
  </style>
</head>
<body>
  <div class="panel">
    <p>Theme colors come from three variables.</p>
    <button id="toggle">Toggle dark mode</button>
    <button id="brand">Random text color</button>
  </div>
  <script>
    const root = document.documentElement;
    document.getElementById('toggle').onclick = () => root.classList.toggle('dark');
    document.getElementById('brand').onclick = () => {
      const hue = Math.floor(Math.random() * 360);
      root.style.setProperty('--text', `hsl(${hue} 70% 40%)`);
      console.log(getComputedStyle(root).getPropertyValue('--text'));
    };
  </script>
</body>
</html>

Relisez une variable avec getComputedStyle(element).getPropertyValue('--text'). Notez que setProperty écrit un style inline sur <html>, qui l'emporte sur la classe .dark : après un clic sur le second bouton, la couleur du texte reste la même dans les deux thèmes tant que la valeur inline n'est pas retirée avec root.style.removeProperty('--text').

Transmettre des valeurs depuis le HTML

Une variable dans un attribut style est la façon la plus propre de passer des données propres à un élément à une feuille de style. Le design reste dans le CSS ; le HTML ne fournit qu'un nombre.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Bars</title>
  <style>
    .bar {
      width: calc(var(--value) * 1%);
      box-sizing: border-box;
      background: #2563eb;
      color: white;
      padding: 4px 8px;
      margin-bottom: 6px;
      border-radius: 4px;
    }
  </style>
</head>
<body>
  <div class="bar" style="--value: 30">30</div>
  <div class="bar" style="--value: 65">65</div>
  <div class="bar" style="--value: 90">90</div>
</body>
</html>

calc(var(--value) * 1%) transforme le simple nombre en pourcentage. Les variables peuvent aussi changer dans une media query : @media (min-width: 900px) { :root { --space: 20px; } } agrandit sur les grands écrans tous les espacements qui lisent --space.

Le piège de la valeur invalide

Le navigateur ne peut pas savoir à l'avance si une variable contient une valeur valide pour la propriété qui l'utilise. Quand ce n'est pas le cas, la propriété ne revient pas à la déclaration précédente de la règle. Elle devient invalide au moment du calcul de la valeur et se comporte comme si elle valait unset : les propriétés héritées prennent la valeur du parent, les autres leur valeur initiale.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Invalid value</title>
  <style>
    :root { --size: red; } /* not a length */
    .box {
      background: #e5e7eb;
      padding: 12px;
      font-size: 24px;
      font-size: var(--size); /* invalid: 24px is NOT kept */
      border: 4px solid #f59e0b;
      border-width: var(--missing); /* undefined, no fallback */
    }
  </style>
</head>
<body>
  <div class="box">16px text and a 3px border, not 24px and 4px.</div>
</body>
</html>

Le texte hérite des 16px de <body>, et border-width revient à sa valeur initiale, medium, que les navigateurs dessinent en 3px. Sans variables, une déclaration invalide est ignorée et celle d'avant survit ; avec des variables, il est trop tard pour cela. Une valeur de secours n'aide pas quand la variable est définie mais fausse : elle ne sert que pour une variable non définie.

Variables CSS et variables Sass

	Variables CSS	Variables Sass
Syntaxe	`--brand: #2563eb;` et `var(--brand)`	`$brand: #2563eb;`
Résolution	Dans le navigateur, en direct	Au build, absentes du résultat
Varier par élément	Oui, par héritage	Non
Varier avec une classe ou une media query	Oui	Non
Modifier depuis JavaScript	Oui	Non
Utiliser dans des sélecteurs ou des conditions de média	Non	Oui

Les deux se complètent : beaucoup de projets utilisent Sass pour la logique au build et produisent des variables CSS pour tout ce qui doit pouvoir changer de thème.

Erreurs courantes

Oublier les deux traits d'union. var(brand) et --brand déclaré sous la forme -brand ne fonctionnent pas.
Utiliser une variable dans une media query. @media (min-width: var(--bp)) n'est pas valide. Les conditions de média demandent des valeurs littérales.
Croire que la déclaration précédente survit à une variable invalide. Ce n'est pas le cas ; voir le piège ci-dessus.
Mal combiner les unités. --gap: 10; puis margin: var(--gap)px ne donne pas 10px. Utilisez calc(var(--gap) * 1px) ou stockez 10px.
Déclarer sur le mauvais élément. Une variable déclarée sur .card n'est visible ni par ses frères ni par son parent ; déclarez les valeurs partagées sur :root.

Questions fréquentes

Comment déclarer une variable CSS ?

Écrivez dans une règle une propriété dont le nom commence par deux traits d'union, en général dans :root pour une valeur globale : :root { --brand: #2563eb; }. Lisez-la n'importe où avec var(--brand), par exemple color: var(--brand);.

Qu'est-ce que :root en CSS ?

:root est une pseudo-classe qui cible l'élément racine du document, <html> dans une page HTML. Les variables déclarées là sont héritées par tous les éléments. Elle a la spécificité d'une classe, donc elle l'emporte sur un simple sélecteur html.

Comment définir une valeur par défaut pour une variable CSS ?

Passez un second argument à var() : color: var(--accent, #2563eb);. La valeur de secours sert quand --accent n'est défini ni sur l'élément ni sur ses ancêtres. Elle ne sert pas quand la variable est définie avec une valeur invalide pour la propriété.

Comment modifier une variable CSS avec JavaScript ?

Appelez setProperty sur le style d'un élément : document.documentElement.style.setProperty('--brand', '#16a34a'). Toutes les règles qui utilisent var(--brand) se mettent à jour d'un coup. Lisez la valeur actuelle avec getComputedStyle(el).getPropertyValue('--brand').

Quelle est la différence entre les variables CSS et les variables Sass ?

Les variables Sass sont remplacées par leur valeur à la compilation de la feuille de style, elles ne peuvent donc pas changer dans le navigateur. Les variables CSS vivent dans le navigateur : elles s'héritent, peuvent varier d'un élément à l'autre, réagissent aux media queries et aux classes, et se modifient depuis JavaScript.

Les noms de variables CSS sont-ils sensibles à la casse ?

Oui. --Brand et --brand sont deux variables différentes, contrairement aux noms de propriétés ordinaires comme color, qui ne sont pas sensibles à la casse.

Concepts liés