CSS変数（カスタムプロパティ）の使い方｜コピペ実例とダークモード切替

CSS変数（カスタムプロパティ）とは、--名前: 値; で宣言し var(--名前) で参照する、ブラウザが実行時に解決する値の入れ物です。 Sass の変数と違ってコンパイル後も CSS に残るため、継承・メディアクエリ・JavaScript から値を差し替えられ、ダークモード切替やコンポーネント単位のテーマに向いています。

この記事では、宣言・参照・フォールバック・継承・無効値・@property・JavaScript からの読み書きを早見表にまとめたうえで、Chromium 141（Playwright 1.56）で getComputedStyle() の解決結果を実測した表を各節に載せます。「型が合わない値を渡すと何が起きるか」「@property で登録した変数はどう補間されるか」「prefers-color-scheme + data-theme + light-dark() のダークモード切替がリロード後も保存されるか」を、コピペできるコードと実行結果で確認できます。

CSS変数の早見表

ブラウザ対応（MDN・web.dev で確認、2026年10月時点）

宣言と参照の基本

カスタムプロパティは -- で始まる名前で宣言し、var() で参照します。 サイト全体で使う値は :root（html 要素）に置くのが定番です。

:root {
  --brand: #2563eb;
  --space: 8px;
}
.btn {
  background: var(--brand);
  padding: var(--space) calc(var(--space) * 2);
}

宣言の時点ではほぼどんな値でも有効で、使う場所で意味を持つかどうかが後で判定されます。 命名は「役割」で付けると差し替えに強くなります。 --blue より --brand、--16px より --space-4 のように用途を表す名前にしておくと、テーマ変更で値だけを入れ替えられます。

var() のフォールバックを使う

var(--名前, 既定値) の2番目の引数は、変数が未定義のときに使われます。 最初のカンマ以降はすべて既定値として扱われるので、カンマを含む値も書けます。

.one   { color: var(--not-defined, red); }
.two   { padding: var(--pad, var(--space-lg, 12px)); }          /* 多段 */
.three { color: var(--not-defined, rgb(0, 128, 0)); }           /* カンマを含む */
.four  { font-family: var(--font, "Noto Sans JP", sans-serif); } /* リストも既定値になる */

フォールバックは「変数が未定義のとき」にだけ効きます。 変数が定義されていて型が合わないときは別の扱い（後述）になります。

継承の実験：親で定義 → 子で上書き → 孫はどちらを見るか

カスタムプロパティは color と同じく継承プロパティなので、親で宣言した値は子孫すべてで参照できます。 途中の要素で再宣言すると、その要素以下は新しい値に切り替わります。

.parent     { --c: blue;  color: var(--c); }
.child      { --c: green; color: var(--c); }   /* .parent の中に置く */
.grandchild { color: var(--c); }               /* .child の中と .parent 直下の両方に置く */

同じ .grandchild クラスでも、置かれた場所によって値が変わります。 コンポーネントの外側から中の色や余白を「注入」できる性質です。

「計算値時に無効」になる例と、initial / inherit / unset の効き方

var() で入れた値がそのプロパティの型に合わないときは「計算値時に無効（invalid at computed-value time）」となり、宣言は unset として扱われます。 通常の構文エラーと違って、同じルール内の前の宣言には戻りません。3パターンを並べて実測しました。

.wrap { color: purple; }                                        /* 親 */
#bad1 { --size: 16px; color: red; color: var(--size); }         /* var() 経由で型違い */
#bad2 { color: red; color: 16px; }                              /* 直接書いた型違い */
#bad3 { --size: 16px; width: 50px; width: var(--size2); }       /* 未定義の変数 */

var() を含む宣言は、ブラウザがパース時に正しさを判断できないのが理由です。防ぐには @property で型を付ける（次節）か、フォールバックを付けます。

initial / inherit / unset をカスタムプロパティに指定したとき

.p4 { --c4: blue; }                             /* 親 */
#u1 { --c4: initial; color: var(--c4, orange); }
#u2 { --c4: inherit; color: var(--c4, orange); }
#u3 { --c4: unset;   color: var(--c4, orange); }

--c4: initial は「この要素以下では変数を消す」操作として使えます。 @property で inherits: false にした変数では、unset は initial-value に戻ります。

@property で型・初期値・継承を決めて、アニメーションさせる

@property は、カスタムプロパティに「型（syntax）」「初期値（initial-value）」「継承するか（inherits）」を登録するアットルールです。 登録すると型に合わない値は初期値に置き換わり、数値や色として補間できるので transition や @keyframes で動かせます。syntax と inherits は必須、initial-value は syntax: "*" 以外では必須です（MDN）。

@property --hue { syntax: "<number>"; inherits: false; initial-value: 0; }
#hue {
  --hue: 0;
  background-color: hsl(var(--hue) 80% 50%);
  animation: spin-hue 2s linear forwards;
}
@keyframes spin-hue { to { --hue: 360; } }

/* 比較用：未登録の変数を同じ keyframes で動かす */
#hue-unreg {
  --hue2: 0;
  background-color: hsl(var(--hue2) 80% 50%);
  animation: spin-hue2 2s linear forwards;
}
@keyframes spin-hue2 { to { --hue2: 360; } }

アニメーション開始から 500ms 後の値です（Chromium 141。数値は実行タイミングで前後します）。

未登録の変数は「文字列」として扱われるため補間できず、途中で一気に切り替わります。 transition: --stop 1s のように transition の対象にもでき、<percentage> で登録した --stop: 20% → 100% のホバーでは 500ms 後に 59.992% でした。グラデーションの角度や色停止位置のようにプロパティ単体では動かせなかった部分も、@property で型を付けるとなめらかにアニメーションできます。

型に合わない値、inherits: false、getComputedStyle の返り値

@property --typed-color { syntax: "<color>"; inherits: false; initial-value: teal; }
#typed-ok  { --typed-color: #ff0000; color: var(--typed-color); }
#typed-bad { --typed-color: 16px;    color: var(--typed-color); }

@property --reg-len { syntax: "<length>"; inherits: true; initial-value: 0px; }
#calc-unreg { --a: 10px; --b: var(--a); --c: calc(var(--a) * 2); }
#calc-reg   { --a: 10px; --reg-len: calc(var(--a) * 2); }

JavaScript で「計算済みの px 値」を読みたいなら @property で登録するのが近道です。 JS から登録するには CSS.registerProperty({ name: '--hue', syntax: '<number>', inherits: false, initialValue: 0 }) を使います。同じ名前を両方で登録した場合は JS 側が優先されます（MDN）。

calc() / clamp() と組み合わせる：スペーシングスケールと流体タイポグラフィ

カスタムプロパティは calc() や clamp() の中でそのまま使えます。 基準値を1つ決めて倍数で派生させると、余白やサイズの体系を一箇所で管理できます。

:root {
  /* スペーシングスケール：基準 4px の倍数 */
  --space-unit: 4px;
  --space-1: calc(var(--space-unit) * 1);   /* 4px  */
  --space-2: calc(var(--space-unit) * 2);   /* 8px  */
  --space-4: calc(var(--space-unit) * 4);   /* 16px */

  /* 流体タイポグラフィ：画面幅に応じて 1rem〜2rem の間でなめらかに変化 */
  --fs-min: 1rem;
  --fs-max: 2rem;
  --fs-fluid: clamp(var(--fs-min), 0.5rem + 2vw, var(--fs-max));
}
.card  { padding: var(--space-2) var(--space-4); margin-top: var(--space-1); }
.title { font-size: var(--fs-fluid); }

clamp(最小, 推奨, 最大) の推奨値に vw を混ぜると、メディアクエリなしで文字サイズが画面幅に追従します。

ダークモード切替のコピペ完成形

方針は「OS 設定に自動追従しつつ、ユーザーが選んだテーマは data-theme 属性で上書きし、localStorage に保存する」です。 color-scheme を宣言しておくと、フォーム部品やスクロールバーの配色も追従し、light-dark() も使えます。HTML・CSS・JS を 1 ファイルにまとめました。

<!doctype html>
<html lang="ja">
<head>
<meta charset="utf-8">
<title>ダークモード切替（CSS変数）</title>
<script>
  // 1) 描画前に保存済みテーマを反映（ちらつき防止のため head の先頭で同期実行）
  try {
    var saved = localStorage.getItem('theme');            // 'light' | 'dark' | null
    if (saved) document.documentElement.dataset.theme = saved;
  } catch (e) {}
</script>
<style>
  /* 2) 既定はライト。OS がダークなら自動でダーク（手動選択がないとき） */
  :root {
    color-scheme: light dark;   /* フォーム部品・スクロールバーも追従し、light-dark() が使える */
    --bg: #ffffff;
    --fg: #1f2937;
    --accent: #2563eb;
  }
  @media (prefers-color-scheme: dark) {
    :root:not([data-theme="light"]) { --bg: #111827; --fg: #f9fafb; --accent: #60a5fa; }
  }
  /* 3) ユーザーが選んだテーマは OS 設定より優先 */
  :root[data-theme="dark"]  { color-scheme: dark;  --bg: #111827; --fg: #f9fafb; --accent: #60a5fa; }
  :root[data-theme="light"] { color-scheme: light; }

  body { margin: 0; padding: 24px; background: var(--bg); color: var(--fg);
         font-family: system-ui, sans-serif; transition: background-color .3s, color .3s; }
  /* 4) light-dark() なら変数を増やさず 1 行で両方の色を書ける */
  .card { padding: 16px; border-radius: 12px;
          background: light-dark(#f3f4f6, #1f2937);
          box-shadow: 0 2px 8px light-dark(rgb(0 0 0 / .08), rgb(0 0 0 / .5)); }
  .btn  { background: var(--accent); color: #fff; border: 0; border-radius: 8px; padding: 8px 16px; }
</style>
</head>
<body>
  <button class="btn" id="theme-toggle" type="button" aria-pressed="false">ダークモード</button>
  <div class="card" id="card">テーマ: <span id="label">-</span></div>
<script>
  // 5) トグル：切替と localStorage 保存
  var root = document.documentElement, btn = document.getElementById('theme-toggle');
  var mq = matchMedia('(prefers-color-scheme: dark)');
  function current() { return root.dataset.theme || (mq.matches ? 'dark' : 'light'); }
  function render() {
    btn.setAttribute('aria-pressed', String(current() === 'dark'));
    document.getElementById('label').textContent = current() + (root.dataset.theme ? '（手動）' : '（OS設定）');
  }
  btn.addEventListener('click', function () {
    var next = current() === 'dark' ? 'light' : 'dark';
    root.dataset.theme = next;
    try { localStorage.setItem('theme', next); } catch (e) {}
    render();
  });
  mq.addEventListener('change', render);   // OS 設定が変わったら表示を更新
  render();
</script>
</body>
</html>

Playwright で OS の配色（colorScheme）を light / dark に切り替え、クリック → リロードの流れを確認しました（Chromium 141、http://127.0.0.1 で配信）。

再クリックでは元のテーマに戻り、localStorage.theme も書き換わりました。data-theme 側で color-scheme を宣言しているため、light-dark() で書いた .card の背景と box-shadow（rgba(0, 0, 0, 0.08) ↔ rgba(0, 0, 0, 0.5)）も手動切替に追従しました。 ボタンの aria-pressed も初期表示で false（OS=light）/ true（OS=dark）でした。

3つの方式の使い分け

コンポーネント単位のテーマとメディアクエリでの再定義

コンポーネントの中では「フォールバックつきの var()」で既定値を持たせ、バリアントのクラスで変数だけを上書きします。 スタイルの本体を1つに保てるので、バリアントが増えても宣言は変数の再定義だけで済みます。

.btn { background: var(--btn-bg, #6b7280); color: var(--btn-fg, #fff); }  /* 既定はグレー */
.btn--primary { --btn-bg: #2563eb; }
.btn--ghost   { --btn-bg: transparent; --btn-fg: #2563eb; }

メディアクエリの中でカスタムプロパティを再定義すると、参照している側のルールを書き直さずに済みます。 repeat() の回数のような単位なし整数も切り替えられます。

:root { --gap: 8px; --cols: 1; }
@media (min-width: 768px) { :root { --gap: 16px; --cols: 3; } }
.grid { display: grid; gap: var(--gap); grid-template-columns: repeat(var(--cols), 1fr); }

JavaScript から読む・書く

読むときは getComputedStyle(el).getPropertyValue('--x')、書くときは el.style.setProperty('--x', 値) です。 el.style.getPropertyValue() はインラインスタイルの値だけを返し、継承やスタイルシートの値は見えません。

コメントは Chromium 141 での実測値です。

<div id="js1" style="--x: 10px; width: var(--x)">js1</div>
<script>
  const el = document.getElementById('js1');
  el.style.getPropertyValue('--x');                 // "10px"（インライン）
  getComputedStyle(el).getPropertyValue('--x');     // "10px"（計算後）
  getComputedStyle(el).getPropertyValue('--nope');  // ""（未定義は空文字）
  el.style.setProperty('--x', '240px');             // width が 10px → 240px に
  // サイト全体の色を差し替え：--brand を参照する要素の color が rgb(37, 99, 235) → rgb(220, 38, 38)
  document.documentElement.style.setProperty('--brand', 'rgb(220, 38, 38)');
  document.documentElement.style.removeProperty('--brand');  // スタイルシートの値 rgb(37, 99, 235) に戻る
</script>

:root の変数を setProperty() で書き換えると、その変数を参照しているすべての要素が一度に変わります。 値は文字列として渡すので、setProperty('--w', w + 'px') のように単位を付け忘れないようにします。

Sass 変数との違い

Sass の $変数 はコンパイル時に値へ置き換わって消え、CSS のカスタムプロパティはブラウザまで届いて実行時に解決されます。 Sass 1.105.1 でコンパイルすると、$brand は #2563eb に置換され、--brand と var(--brand) はそのまま出力されました。

$brand: #2563eb;            // Sass 変数：コンパイル後は消える
:root { --brand: #2563eb; } // CSS 変数：そのまま出力される
.btn     { background: $brand; }       // → background: #2563eb;
.btn-css { background: var(--brand); } // → background: var(--brand);
@media (min-width: 768px) {
  .btn { --brand: #1d4ed8; }           // CSS 変数はメディアクエリで再定義できる
}

ブレークポイントやセレクタの組み立てには Sass 変数、色・余白・テーマの切替にはカスタムプロパティ、という分担で併用するのが実務では自然です。

よくあるつまずきと直し方

つまずきの多くは「var() はプロパティ値の位置でしか使えない」「値は文字列として置き換わるだけ」の2点に集約されます。 「起きること」は Chromium 141 の実測です。

@property で syntax: "<length>" を付けておくと、#1 のような単位の不一致は初期値に置き換わって表示が保たれます。 DevTools の「Computed」パネルで -- から始まる行を見ると、値がどこで変わったかを追えます。

よくある質問

Q. :root と html のどちらに宣言すればよいですか？ A. どちらも同じ html 要素を指しますが、:root は擬似クラスなので詳細度が html（0-0-1）より高い 0-1-0 で、他のルールに上書きされにくい違いがあります。慣例として :root が広く使われています。

Q. var() の中で var() を使えますか？ A. 使えます。--b: var(--a) のように変数から変数を参照でき、getComputedStyle では参照が置き換わった値（実測 "10px"）が返ります。--a: var(--b); --b: var(--a); のような循環参照は両方が未定義扱いになり、フォールバックが効きます（実測：var(--a, orange) が orange）。

Q. @property に対応していないブラウザではどうなりますか？ A. @property ブロックが無視され、変数は「型なし」として動きます。値の参照は問題なく動き、アニメーションだけ補間されずに切り替わります。var(--x, 既定値) のフォールバックも併記しておくと安心です。

まとめ

• --名前: 値 で宣言、var(--名前, 既定値) で参照。 既定値は「未定義のとき」にだけ効く
• カスタムプロパティは常に継承する。 子で再宣言すればその要素以下だけ切り替わり、--x: initial で未定義に戻せる
• 型が合わない値は「計算値時に無効」となり unset 扱い。 color なら親の色、width なら auto になる
• @property で型・初期値・継承を登録すると、数値・色・%をアニメーションで補間できる（Chrome/Edge 85、Firefox 128、Safari 16.4 以降）
• calc() / clamp() と組み合わせて、スペーシングスケールや流体タイポグラフィを一箇所で管理できる
• ダークモードは prefers-color-scheme で自動追従、data-theme で手動上書き、light-dark() で1行化、localStorage で保存
• JS は getComputedStyle().getPropertyValue() で読み、style.setProperty() で書く。 var() はセレクタやメディアクエリの条件では使えない

株式会社RJCでは、こうした CSS の仕様をブラウザで実際に動かして確かめながら、プロジェクトの中で仲間と学び合っています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。