実行できるCSSドキュメント: CSS 変数

Q: CSS 変数はどう宣言しますか？

ルールの中に、名前が 2 つのハイフンで始まるプロパティを書きます。グローバルな値なら通常は :root に書きます: :root { --brand: #2563eb; }。どこからでも var(--brand) で読み取れます。例: color: var(--brand);。

Q: CSS の :root とは何ですか？

:root は文書のルート要素に一致する疑似クラスで、HTML ページでは です。ここで宣言した変数はすべての要素に継承されます。詳細度はクラスと同じなので、単なる html セレクタに勝ちます。

Q: CSS 変数に初期値 (デフォルト値) を設定するには？

var() に 2 つ目の引数を渡します: color: var(--accent, #2563eb);。要素にも祖先にも --accent が定義されていないときにフォールバックが使われます。変数が定義されていて、その値がプロパティにとって無効な場合には使われません。

Q: JavaScript で CSS 変数を変更するには？

要素の style に対して setProperty を呼びます: document.documentElement.style.setProperty('--brand', '#16a34a')。var(--brand) を使うすべてのルールが一度に更新されます。現在の値は getComputedStyle(el).getPropertyValue('--brand') で読み取れます。

Q: CSS 変数の名前は大文字と小文字を区別しますか？

区別します。--Brand と --brand は別の変数です。大文字と小文字を区別しない color などの通常のプロパティ名とは異なります。

CSS 変数の宣言と使い方

CSS 変数、正式には カスタムプロパティ は、名前が -- で始まるプロパティです。一度だけ宣言し (ページ全体に継承させるため、ふつうは :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 に書き換えると、カードの枠線とボタンが一緒に変わります。これが要点です。値は 1 つ、変更する場所も 1 か所です。ボタンの左右の padding のように、変数は 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>

バリエーションは変数だけを設定し、枠線そのものには触れていません。4 つ目のバリエーションを追加するのも 1 行で済みます。

フォールバック値

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 クラスに勝つことに注意してください。2 つ目のボタンを押した後は、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>

文字は <body> から 16px を継承し、border-width は初期値の medium に戻ります。ブラウザはこれを 3px で描画します。変数を使わない場合、無効な宣言は捨てられ、その前の宣言が残ります。変数を使う場合は、その判断をするには遅すぎるのです。変数が定義されていて値が間違っているときは、フォールバックも役に立ちません。フォールバックは未定義の変数のためだけのものです。

CSS 変数と Sass 変数の比較

	CSS 変数	Sass 変数
書き方	`--brand: #2563eb;` と `var(--brand)`	`$brand: #2563eb;`
解決されるタイミング	ブラウザ内でリアルタイムに	ビルド時。出力には残らない
要素ごとの変更	可能 (継承による)	不可
クラスやメディアクエリでの変更	可能	不可
JavaScript からの変更	可能	不可
セレクタやメディア条件での使用	不可	可能

2 つは組み合わせて使えます。多くのプロジェクトでは、ビルド時のロジックに Sass を使い、テーマで変えたいものは CSS 変数として出力しています。

よくある間違い

2 つのハイフンを忘れる。 var(brand) や、-brand として宣言した --brand は動きません。
メディアクエリで変数を使う。 @media (min-width: var(--bp)) は無効です。メディア条件にはリテラル値が必要です。
無効な変数でも前の宣言が残ると思う。 残りません。上の落とし穴を参照してください。
単位の組み合わせを間違える。 --gap: 10; として margin: var(--gap)px と書いても 10px にはなりません。calc(var(--gap) * 1px) を使うか、10px を格納しましょう。
間違った要素で宣言する。 .card で宣言した変数は、兄弟要素や親要素からは見えません。共有する値は :root で宣言しましょう。

よくある質問

CSS 変数はどう宣言しますか？

ルールの中に、名前が 2 つのハイフンで始まるプロパティを書きます。グローバルな値なら通常は :root に書きます: :root { --brand: #2563eb; }。どこからでも var(--brand) で読み取れます。例: color: var(--brand);。

CSS の :root とは何ですか？

:root は文書のルート要素に一致する疑似クラスで、HTML ページでは <html> です。ここで宣言した変数はすべての要素に継承されます。詳細度はクラスと同じなので、単なる html セレクタに勝ちます。

CSS 変数に初期値 (デフォルト値) を設定するには？

var() に 2 つ目の引数を渡します: color: var(--accent, #2563eb);。要素にも祖先にも --accent が定義されていないときにフォールバックが使われます。変数が定義されていて、その値がプロパティにとって無効な場合には使われません。

JavaScript で CSS 変数を変更するには？

要素の style に対して setProperty を呼びます: document.documentElement.style.setProperty('--brand', '#16a34a')。var(--brand) を使うすべてのルールが一度に更新されます。現在の値は getComputedStyle(el).getPropertyValue('--brand') で読み取れます。

CSS 変数と Sass 変数の違いは何ですか？

Sass 変数はスタイルシートのコンパイル時に値に置き換えられるため、ブラウザ上では変更できません。CSS 変数はブラウザの中で生きています。継承され、要素ごとに値を変えられ、メディアクエリやクラスに反応し、JavaScript から変更できます。

CSS 変数の名前は大文字と小文字を区別しますか？

区別します。--Brand と --brand は別の変数です。大文字と小文字を区別しない color などの通常のプロパティ名とは異なります。