:root è una pseudo-classe che seleziona l'elemento radice del documento, che in una pagina HTML è . Le variabili dichiarate lì vengono ereditate da ogni elemento. Ha la specificità di una classe, quindi batte un semplice selettore html.

Guida CSS interattiva: Variabili CSS

Q: Come si imposta un valore di default per una variabile CSS?

Passa un secondo argomento a var(): color: var(--accent, #2563eb);. Il fallback viene usato quando --accent non è definita sull'elemento o sui suoi antenati. Non viene usato quando la variabile è definita con un valore non valido per la proprietà.

Q: Come si cambia una variabile CSS con JavaScript?

Chiama setProperty sullo style di un elemento: document.documentElement.style.setProperty('--brand', '#16a34a'). Tutte le regole che usano var(--brand) si aggiornano insieme. Leggi il valore corrente con getComputedStyle(el).getPropertyValue('--brand').

Q: I nomi delle variabili CSS distinguono maiuscole e minuscole?

Sì. --Brand e --brand sono due variabili diverse, a differenza dei normali nomi di proprietà come color, che non le distinguono.

Dichiarare e usare una variabile CSS

Una variabile CSS, ufficialmente una custom property, è una proprietà il cui nome inizia con --. Dichiarala una volta, di solito su :root così tutta la pagina la eredita, e leggila ovunque con 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>

Cambia --brand in #16a34a e il bordo della card e il pulsante cambiano insieme. È proprio questo il punto: un valore, un solo posto dove cambiarlo. Le variabili si combinano anche con calc(), come mostra il padding laterale del pulsante.

Sintassi

: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 */
}

Regola	Dettaglio
Nome	Inizia con `--`, poi lettere, cifre, `-` o `_`. Distingue maiuscole e minuscole: `--Brand` non è `--brand`.
Valore	Quasi qualsiasi cosa: un colore, una lunghezza, una lista, una stringa. Non viene controllato finché non viene usato.
Dove dichiararla	In qualsiasi regola. `:root` per le globali, il selettore di un componente per i valori locali.
Ereditarietà	Le custom properties si ereditano, quindi un figlio vede i valori dei suoi antenati.
Dove funziona `var()`	Solo nei valori delle proprietà, non nei selettori, nei nomi delle proprietà o nelle condizioni `@media`.

:root seleziona l'elemento <html>. Si usa al posto di html perché ha la specificità di una classe e, per convenzione, indica "impostazioni globali".

Ambito: sovrascrivere una variabile per componente

Dato che le variabili si ereditano, dichiararne di nuovo una su un elemento la cambia per quell'elemento e per tutto ciò che contiene. La regola che usa la variabile resta la stessa.

<!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>

Le varianti impostano solo una variabile, mai il bordo in sé. Aggiungere una quarta variante è una riga.

Valori di fallback

var(--name, fallback) usa il fallback quando la variabile non è definita sull'elemento né su alcun antenato. Tutto ciò che viene dopo la prima virgola è il fallback, quindi può contenere a sua volta delle virgole (var(--font, Georgia, serif)) e può essere un altro 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>

Cambiare le variabili con JavaScript: un selettore di tema

JavaScript può impostare una variabile su qualsiasi elemento con style.setProperty(). Impostala su document.documentElement (l'elemento <html>) e tutta la pagina la segue. Lo schema più comune attiva e disattiva una classe che ridefinisce le variabili:

<!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>

Rileggi una variabile con getComputedStyle(element).getPropertyValue('--text'). Nota che setProperty scrive uno stile inline su <html>, che batte la classe .dark, quindi dopo aver premuto il secondo pulsante il colore del testo resta fisso in entrambi i temi finché il valore inline non viene rimosso con root.style.removeProperty('--text').

Passare valori dall'HTML

Una variabile in un attributo style è il modo più pulito per passare dati di ogni elemento a un foglio di stile. Il design resta nel CSS; l'HTML fornisce solo un numero.

<!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%) trasforma il numero semplice in una percentuale. Le variabili possono anche cambiare dentro una media query: @media (min-width: 900px) { :root { --space: 20px; } } fa crescere sugli schermi larghi ogni spaziatura che legge --space.

La trappola del valore non valido

Il browser non può sapere in anticipo se una variabile contiene un valore valido per la proprietà che la usa. Quando non lo contiene, la proprietà non torna alla dichiarazione precedente nella regola. Diventa non valida al momento del valore calcolato e si comporta come se fosse impostata a unset: le proprietà ereditate prendono il valore del genitore, le altre il loro valore iniziale.

<!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>

Il testo eredita 16px da <body>, e border-width torna al suo valore iniziale, medium, che i browser disegnano come 3px. Senza variabili, una dichiarazione non valida viene scartata e quella precedente sopravvive; con le variabili, è troppo tardi per farlo. Un fallback non aiuta quando la variabile è definita ma sbagliata: il fallback vale solo per una variabile non definita.

Variabili CSS vs variabili Sass

	Variabili CSS	Variabili Sass
Sintassi	`--brand: #2563eb;` e `var(--brand)`	`$brand: #2563eb;`
Quando vengono risolte	Nel browser, dal vivo	In fase di build, spariscono dall'output
Cambiare per elemento	Sì, per ereditarietà	No
Cambiare con una classe o una media query	Sì	No
Cambiare da JavaScript	Sì	No
Usare in selettori o condizioni media	No	Sì

Le due lavorano insieme: molti progetti usano Sass per la logica in fase di build e generano variabili CSS per tutto ciò che deve cambiare con il tema.

Errori comuni

Dimenticare i due trattini. var(brand) e --brand dichiarata come -brand non funzionano.
Usare una variabile in una media query. @media (min-width: var(--bp)) non è valido. Le condizioni media hanno bisogno di valori letterali.
Aspettarsi che la dichiarazione precedente sopravviva a una variabile non valida. Non sopravvive; vedi la trappola qui sopra.
Combinare le unità nel modo sbagliato. --gap: 10; e poi margin: var(--gap)px non produce 10px. Usa calc(var(--gap) * 1px) o memorizza 10px.
Dichiararla sull'elemento sbagliato. Una variabile dichiarata su .card non è visibile ai suoi fratelli né al genitore; dichiara i valori condivisi su :root.

Domande frequenti

Come si dichiara una variabile CSS?

Scrivi dentro una regola una proprietà il cui nome inizia con due trattini, di solito in :root per un valore globale: :root { --brand: #2563eb; }. Leggila ovunque con var(--brand), per esempio color: var(--brand);.

Cos'è :root in CSS?

:root è una pseudo-classe che seleziona l'elemento radice del documento, che in una pagina HTML è <html>. Le variabili dichiarate lì vengono ereditate da ogni elemento. Ha la specificità di una classe, quindi batte un semplice selettore html.

Come si imposta un valore di default per una variabile CSS?

Passa un secondo argomento a var(): color: var(--accent, #2563eb);. Il fallback viene usato quando --accent non è definita sull'elemento o sui suoi antenati. Non viene usato quando la variabile è definita con un valore non valido per la proprietà.

Come si cambia una variabile CSS con JavaScript?

Chiama setProperty sullo style di un elemento: document.documentElement.style.setProperty('--brand', '#16a34a'). Tutte le regole che usano var(--brand) si aggiornano insieme. Leggi il valore corrente con getComputedStyle(el).getPropertyValue('--brand').

Che differenza c'è tra variabili CSS e variabili Sass?

Le variabili Sass vengono sostituite dai loro valori quando il foglio di stile viene compilato, quindi non possono cambiare nel browser. Le variabili CSS vivono nel browser: si ereditano, possono essere diverse per ogni elemento, rispondono a media query e classi, e si possono cambiare da JavaScript.

I nomi delle variabili CSS distinguono maiuscole e minuscole?

Sì. --Brand e --brand sono due variabili diverse, a differenza dei normali nomi di proprietà come color, che non le distinguono.

Concetti correlati