Docs ejecutables de CSS: Variables CSS

Q: ¿Qué es :root en CSS?

:root es una pseudoclase que selecciona el elemento raíz del documento, que en una página HTML es . Todos los elementos heredan las variables declaradas ahí. Tiene la especificidad de una clase, así que le gana a un selector html simple.

Q: ¿Cómo se pone un valor por defecto a una variable CSS?

Pasa un segundo argumento a var(): color: var(--accent, #2563eb);. El valor de respaldo se usa cuando --accent no está definida en el elemento ni en sus ancestros. No se usa cuando la variable está definida con un valor inválido para la propiedad.

Q: ¿Cómo se cambia una variable CSS con JavaScript?

Llama a setProperty sobre el style de un elemento: document.documentElement.style.setProperty('--brand', '#16a34a'). Todas las reglas que usan var(--brand) se actualizan a la vez. Lee el valor actual con getComputedStyle(el).getPropertyValue('--brand').

Q: ¿Los nombres de las variables CSS distinguen mayúsculas y minúsculas?

Sí. --Brand y --brand son dos variables distintas, a diferencia de los nombres de propiedades normales como color, que no las distinguen.

Declarar y usar una variable CSS

Una variable CSS, oficialmente una custom property, es una propiedad cuyo nombre empieza con --. Declárala una vez, normalmente en :root para que toda la página la herede, y léela en cualquier parte 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 a #16a34a y el borde de la tarjeta y el botón cambian juntos. De eso se trata: un valor, un solo lugar para cambiarlo. Las variables también se combinan con calc(), como muestra el padding lateral del botón.

Sintaxis

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

Regla	Detalle
Nombre	Empieza con `--` y sigue con letras, dígitos, `-` o `_`. Distingue mayúsculas: `--Brand` no es `--brand`.
Valor	Casi cualquier cosa: un color, una longitud, una lista, un string. No se valida hasta que se usa.
Dónde declararla	En cualquier regla. `:root` para las globales, el selector de un componente para valores locales.
Herencia	Las custom properties se heredan, así que un hijo ve los valores de sus ancestros.
Dónde funciona `var()`	Solo en valores de propiedades, no en selectores, nombres de propiedades ni condiciones `@media`.

:root selecciona el elemento <html>. Se usa en lugar de html porque tiene la especificidad de una clase y, por convención, indica "configuración global".

Alcance: sobrescribir una variable por componente

Como las variables se heredan, volver a declarar una en un elemento la cambia para ese elemento y todo lo que contiene. La regla que usa la variable sigue igual.

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

Las variantes solo definen una variable, nunca el borde en sí. Agregar una cuarta variante es una línea.

Valores de respaldo

var(--name, fallback) usa el valor de respaldo cuando la variable no está definida en el elemento ni en ningún ancestro. Todo lo que va después de la primera coma es el respaldo, así que puede contener comas (var(--font, Georgia, serif)) y puede ser otro 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>

Cambiar variables con JavaScript: un cambio de tema

JavaScript puede definir una variable en cualquier elemento con style.setProperty(). Defínela en document.documentElement (el elemento <html>) y toda la página la sigue. El patrón más común alterna una clase que redefine las 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>

Lee una variable con getComputedStyle(element).getPropertyValue('--text'). Ten en cuenta que setProperty escribe un estilo en línea en <html>, que le gana a la clase .dark, así que después de presionar el segundo botón el color del texto no cambia en ninguno de los dos temas hasta que se quite el valor en línea con root.style.removeProperty('--text').

Pasar valores desde el HTML

Una variable en un atributo style es la forma más limpia de pasarle datos de cada elemento a una hoja de estilo. El diseño se queda en el CSS; el HTML solo aporta un número.

<!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%) convierte el número simple en un porcentaje. Las variables también pueden cambiar dentro de una media query: @media (min-width: 900px) { :root { --space: 20px; } } hace que todo espaciado que lee --space crezca en pantallas anchas.

La trampa del valor inválido

El navegador no puede saber de antemano si una variable tiene un valor válido para la propiedad que la usa. Cuando no lo tiene, la propiedad no vuelve a la declaración anterior de la regla. Pasa a ser inválida en el momento del valor calculado y se comporta como si valiera unset: las propiedades heredables toman el valor del padre y las demás toman su valor inicial.

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

El texto hereda 16px de <body>, y border-width vuelve a su valor inicial, medium, que los navegadores dibujan como 3px. Sin variables, una declaración inválida se descarta y la anterior sobrevive; con variables, ya es tarde para eso. Un valor de respaldo no ayuda cuando la variable está definida pero es incorrecta: el respaldo es solo para una variable no definida.

Variables CSS vs variables de Sass

	Variables CSS	Variables de Sass
Sintaxis	`--brand: #2563eb;` y `var(--brand)`	`$brand: #2563eb;`
Cuándo se resuelven	En el navegador, en vivo	Al compilar, desaparecen del resultado
Cambiar por elemento	Sí, por herencia	No
Cambiar con una clase o media query	Sí	No
Cambiar desde JavaScript	Sí	No
Usar en selectores o condiciones de media	No	Sí

Las dos funcionan juntas: muchos proyectos usan Sass para la lógica en tiempo de compilación y generan variables CSS para todo lo que se pueda personalizar con temas.

Errores comunes

Olvidar los dos guiones. var(brand) y --brand declarada como -brand no funcionan.
Usar una variable en una media query. @media (min-width: var(--bp)) no es válido. Las condiciones de media necesitan valores literales.
Esperar que la declaración anterior sobreviva a una variable inválida. No sobrevive; mira la trampa de arriba.
Combinar unidades de forma incorrecta. --gap: 10; y luego margin: var(--gap)px no produce 10px. Usa calc(var(--gap) * 1px) o guarda 10px.
Declararla en el elemento equivocado. Una variable declarada en .card no es visible para sus hermanos ni para su padre; declara los valores compartidos en :root.

Preguntas frecuentes

¿Cómo se declara una variable CSS?

Escribe dentro de una regla una propiedad cuyo nombre empiece con dos guiones, normalmente en :root para un valor global: :root { --brand: #2563eb; }. Léela en cualquier parte con var(--brand), por ejemplo color: var(--brand);.

¿Qué es :root en CSS?

:root es una pseudoclase que selecciona el elemento raíz del documento, que en una página HTML es <html>. Todos los elementos heredan las variables declaradas ahí. Tiene la especificidad de una clase, así que le gana a un selector html simple.

¿Cómo se pone un valor por defecto a una variable CSS?

Pasa un segundo argumento a var(): color: var(--accent, #2563eb);. El valor de respaldo se usa cuando --accent no está definida en el elemento ni en sus ancestros. No se usa cuando la variable está definida con un valor inválido para la propiedad.

¿Cómo se cambia una variable CSS con JavaScript?

Llama a setProperty sobre el style de un elemento: document.documentElement.style.setProperty('--brand', '#16a34a'). Todas las reglas que usan var(--brand) se actualizan a la vez. Lee el valor actual con getComputedStyle(el).getPropertyValue('--brand').

¿Qué diferencia hay entre las variables CSS y las variables de Sass?

Las variables de Sass se reemplazan por sus valores al compilar la hoja de estilo, así que no pueden cambiar en el navegador. Las variables CSS viven en el navegador: se heredan, pueden ser distintas en cada elemento, responden a media queries y clases, y se pueden cambiar desde JavaScript.

¿Los nombres de las variables CSS distinguen mayúsculas y minúsculas?

Sí. --Brand y --brand son dos variables distintas, a diferencia de los nombres de propiedades normales como color, que no las distinguen.

Conceptos relacionados