Исполняемые доки CSS: Переменные CSS

Q: Что такое :root в CSS?

:root это псевдокласс, который соответствует корневому элементу документа, в HTML-странице это . Объявленные в нем переменные наследуют все элементы. Его специфичность как у класса, поэтому он сильнее простого селектора html.

Q: Как задать значение по умолчанию для переменной CSS?

Передайте в var() второй аргумент: color: var(--accent, #2563eb);. Запасное значение используется, когда --accent не определена на элементе и его предках. Оно не используется, если переменная определена, но ее значение невалидно для свойства.

Q: Как изменить переменную CSS через JavaScript?

Вызовите setProperty у стиля элемента: document.documentElement.style.setProperty('--brand', '#16a34a'). Все правила с var(--brand) обновятся сразу. Текущее значение читается через getComputedStyle(el).getPropertyValue('--brand').

Q: Учитывается ли регистр в именах переменных CSS?

Да. --Brand и --brand это две разные переменные, в отличие от имен обычных свойств вроде color, где регистр не важен.

Как объявить и использовать переменную CSS

Переменная CSS, официально custom property (пользовательское свойство), это свойство, имя которого начинается с --. Объявите ее один раз, обычно в :root, чтобы ее унаследовала вся страница, и читайте где угодно через 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>

Измените --brand на #16a34a, и рамка карточки и кнопка поменяются вместе. В этом весь смысл: одно значение, одно место для правки. Переменные сочетаются и с calc(), как показывают боковые отступы кнопки.

Синтаксис

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

Правило	Подробности
Имя	Начинается с `--`, затем буквы, цифры, `-` или `_`. Регистр важен: `--Brand` это не `--brand`.
Значение	Почти что угодно: цвет, длина, список, строка. Оно не проверяется, пока его не используют.
Где объявлять	В любом правиле. `:root` для глобальных, селектор компонента для локальных значений.
Наследование	Пользовательские свойства наследуются, поэтому дочерний элемент видит значения предков.
Где работает `var()`	Только в значениях свойств, не в селекторах, не в именах свойств и не в условиях `@media`.

:root соответствует элементу <html>. Его используют вместо html, потому что специфичность у него как у класса, а по соглашению он обозначает «глобальные настройки».

Область видимости: переопределение переменной в компоненте

Переменные наследуются, поэтому повторное объявление на элементе меняет ее для этого элемента и всего, что внутри. Правило, которое использует переменную, остается прежним.

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

Варианты задают только переменную, а не саму рамку. Четвертый вариант добавляется одной строкой.

Значения по умолчанию

var(--name, fallback) использует запасное значение, когда переменная не определена ни на элементе, ни на одном предке. Все после первой запятой считается запасным значением, поэтому в нем самом могут быть запятые (var(--font, Georgia, serif)), и это может быть другой 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>

Изменение переменных через JavaScript: переключатель темы

JavaScript может задать переменную на любом элементе через style.setProperty(). Задайте ее на document.documentElement (элемент <html>), и за ней последует вся страница. Чаще переключают класс, который переопределяет переменные:

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

Значение переменной читается через getComputedStyle(element).getPropertyValue('--text'). Учтите, что setProperty записывает встроенный стиль на <html>, который сильнее класса .dark, поэтому после нажатия второй кнопки цвет текста остается прежним в обеих темах, пока встроенное значение не удалят через root.style.removeProperty('--text').

Передача значений из HTML

Переменная в атрибуте style это самый чистый способ передать таблице стилей данные конкретного элемента. Дизайн остается в CSS, а HTML дает только число.

<!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%) превращает простое число в проценты. Переменные могут меняться и внутри медиазапроса: @media (min-width: 900px) { :root { --space: 20px; } } увеличивает на широких экранах все отступы, которые читают --space.

Ловушка невалидного значения

Браузер не может заранее знать, подходит ли значение переменной для свойства, которое ее использует. Если не подходит, свойство не откатывается к предыдущему объявлению в правиле. Оно становится невалидным на этапе вычисления значения и ведет себя так, будто ему задано unset: наследуемые свойства берут значение родителя, остальные свое начальное значение.

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

Текст наследует 16px от <body>, а border-width возвращается к начальному значению medium, которое браузеры рисуют как 3px. Без переменных невалидное объявление отбрасывается и предыдущее остается в силе; с переменными для этого уже поздно. Запасное значение не помогает, когда переменная определена, но неверна: оно только для неопределенной переменной.

Переменные CSS и переменные Sass

	Переменные CSS	Переменные Sass
Синтаксис	`--brand: #2563eb;` и `var(--brand)`	`$brand: #2563eb;`
Когда вычисляются	В браузере, на лету	При сборке, в результат не попадают
Разные значения у элементов	Да, через наследование	Нет
Смена через класс или медиазапрос	Да	Нет
Смена из JavaScript	Да	Нет
Использование в селекторах и условиях media	Нет	Да

Они работают вместе: многие проекты используют Sass для логики на этапе сборки и выдают CSS-переменные для всего, что должно меняться темой.

Частые ошибки

Забытые два дефиса. var(brand) и --brand, объявленная как -brand, не работают.
Переменная в медиазапросе. @media (min-width: var(--bp)) невалидно. В условиях media нужны буквальные значения.
Ожидание, что предыдущее объявление переживет невалидную переменную. Не переживет; смотрите ловушку выше.
Неправильное сочетание единиц. --gap: 10; и затем margin: var(--gap)px не дают 10px. Используйте calc(var(--gap) * 1px) или храните 10px.
Объявление не на том элементе. Переменную, объявленную на .card, не видят его соседи и родитель; общие значения объявляйте на :root.

Часто задаваемые вопросы

Как объявить переменную CSS?

Запишите внутри правила свойство, имя которого начинается с двух дефисов, для глобального значения обычно в :root: :root { --brand: #2563eb; }. Читайте ее где угодно через var(--brand), например color: var(--brand);.

Что такое :root в CSS?

:root это псевдокласс, который соответствует корневому элементу документа, в HTML-странице это <html>. Объявленные в нем переменные наследуют все элементы. Его специфичность как у класса, поэтому он сильнее простого селектора html.

Как задать значение по умолчанию для переменной CSS?

Передайте в var() второй аргумент: color: var(--accent, #2563eb);. Запасное значение используется, когда --accent не определена на элементе и его предках. Оно не используется, если переменная определена, но ее значение невалидно для свойства.

Как изменить переменную CSS через JavaScript?

Вызовите setProperty у стиля элемента: document.documentElement.style.setProperty('--brand', '#16a34a'). Все правила с var(--brand) обновятся сразу. Текущее значение читается через getComputedStyle(el).getPropertyValue('--brand').

Чем переменные CSS отличаются от переменных Sass?

Переменные Sass заменяются значениями при компиляции таблицы стилей, поэтому в браузере они меняться не могут. Переменные CSS живут в браузере: наследуются, могут отличаться у разных элементов, реагируют на медиазапросы и классы и меняются из JavaScript.

Учитывается ли регистр в именах переменных CSS?

Да. --Brand и --brand это две разные переменные, в отличие от имен обычных свойств вроде color, где регистр не важен.

Связанные концепции