CSSのカスタムプロパティ(CSS変数)の基本的な使い方
CSS のカスタムプロパティ(CSS 変数)を使うと、サイトのテーマカラーや余白の大きさを1か所に書いておき、いろいろな場所から var() で読めます。値は HTML の親から子へ受け継がれるので、ページ全体の値と、カードの中だけの値を分けて持てます。受け継がれる範囲、var(--x, 既定値) の既定値が使われる場合と使われない場合、JavaScript から値を読み書きする方法を、ブラウザーで計算値を読んで確かめました。
検証環境は Ubuntu 24.04、Node.js 22.23.4、Playwright 1.63.0、ヘッドレスの Chromium 153 です。HTML と CSS のページを Playwright で開き、getComputedStyle() で計算値を読みました。Firefox と Safari、型や初期値を決める @property は試していません。
定義して var() で読む
カスタムプロパティは、-- で始まる名前のプロパティです。ふつうのプロパティと同じようにルールの中に書き、使う側では var(--名前) で読みます。ページ全体で使う値は、MDN の「CSS カスタムプロパティ(変数)の使用」にあるように、:root(<html> 要素)に書くのが一般的です。
:root {
--accent: #00c8e8;
}
.box {
background: var(--accent);
}
検証環境では、.box の background-color は rgb(0, 200, 232) になりました。
名前は大文字と小文字を区別します。--Accent に赤を入れた要素で var(--accent) を読むと、赤ではなく :root の --accent の水色になりました。
値は親から子へ受け継がれる
カスタムプロパティは、color と同じように、親の値が子に受け継がれます(仕様の定義で「Inherited: yes」)。そのため、途中の要素で値を書き直すと、その要素の中だけ値が変わります。
:root { --accent: #00c8e8; }
.card { --accent: #d85878; } /* .card の中だけ、ピンクにする */
.box { background: var(--accent); }
.card の外の .box は水色、.card の中の .box は、さらに1段内側に入れてもピンクでした。getComputedStyle() で各要素の --accent を読むと、.card とその子孫では #d85878 が返りました。
受け継ぐのは子孫だけです。兄弟の要素には届きません。.a { --only-a: red; } を付けた要素のすぐ隣の要素で --only-a を読むと、空の文字列が返り、var(--only-a, gray) は灰色になりました。値を共有したい要素どうしの、共通の親(多くの場合は :root)に書きます。
var() の既定値が使われるとき
var() の2つ目の引数は、カスタムプロパティが使えないときの既定値(MDN では「代替値」)です。MDN の var() のページにあるとおり、変数が定義されていないときは既定値が使われます。検証環境では、値に initial を入れたときも既定値が使われました。
.parent { --reset: initial; }
.undef { color: var(--undefined, green); } /* どこにも定義していない */
.reset { color: var(--reset, green); } /* initial を入れた */
どちらも緑(rgb(0, 128, 0))になりました。--reset を getPropertyValue() で読むと、空の文字列でした。仕様の Guaranteed-Invalid Values の節にあるとおり、initial を入れると、定義していないときと同じ状態に戻ります。
既定値は、最初のカンマから ) の手前までがまとめて1つの値になります。font-family: var(--undefined, "Noto Sans CJK JP", sans-serif) の計算値は "Noto Sans CJK JP", sans-serif で、2つの書体の並びがそのまま使われました。既定値をさらに別の変数にしたいときは、var(--a, var(--b, orange)) のように入れ子にします。--a も --b もない要素では、オレンジ(rgb(255, 165, 0))になりました。
値が合わないときは、既定値は使われない
間違えやすいのは、変数は定義されているのに、値が使う場所に合わない場合です。親の文字色をピンクにして、--size: 16px を入れ、子で color に使いました。
.parent { color: rgb(216, 88, 120); --size: 16px; }
.badtype { color: var(--size, green); }
.normal-invalid { color: blue; color: 16px; }
.var-invalid { color: blue; color: var(--size); }
| 書き方 | 文字色 |
|---|---|
color: var(--size, green) |
親のピンク |
color: blue; color: 16px; |
青 |
color: blue; color: var(--size); |
親のピンク |
--size は定義されているので、既定値の緑は使われません。16px を color に入れることになり、その宣言は無効になります。
ふつうに color: 16px と書いた場合は、ブラウザーが CSS を読む時点でこの宣言を捨てるので、その前の color: blue が残りました。一方、var() を使った宣言は、読む時点ではまだ有効として扱われ、計算値を出すときに初めて無効と分かります。このとき、前の color: blue には戻らず、color のように受け継ぐプロパティは親の値、受け継がないプロパティは初期値になります。MDN の「CSS カスタムプロパティ(変数)の使用」にある「無効なカスタムプロパティ」の節の説明と同じ結果です。受け継がない margin-top で margin-top: 20px; margin-top: var(--accent);(--accent は色)と書くと、20px ではなく初期値の 0px になりました。
var() の既定値が効くのは、変数がないときや initial を入れたときです。変数に合わない値が入っていると既定値は使われず、同じルールの前の行の値にも戻りません。
JavaScript で値を読む・変える
JavaScript からは、style.setProperty() と getPropertyValue() を使います。MDN の同じページにある「JavaScript での値」の節にも、この書き方が載っています。
const root = document.documentElement;
// 値を変える(<html> の style 属性に書かれる)
root.style.setProperty("--accent", "#067a98");
// 要素に効いている値を読む
getComputedStyle(root).getPropertyValue("--accent"); // "#067a98"
// style 属性に書いた値を消して、CSS の値に戻す
root.style.removeProperty("--accent");
検証環境で :root の --accent を #067a98 に変えると、<html> の style 属性は --accent: #067a98; になり、.card の外の箱は濃い水色(rgb(6, 122, 152))に変わりました。getComputedStyle(root).getPropertyValue("--accent") も "#067a98" を返しました。.card の中の箱は、.card で書き直したピンクのままでした。:root の値を変えても、途中で書き直している要素の内側には届きません。

.card の中も変えたいときは、.card の要素で setProperty() を呼びます。#2e7d32 を入れると、.card の中の箱は2つとも rgb(46, 125, 50) になりました。removeProperty() で消すと、スタイルシートに書いた値に戻ります。.card から消すと中の箱はピンク(rgb(216, 88, 120))に、:root から消すと外の箱は元の rgb(0, 200, 232) に戻りました。
読むときは getComputedStyle を使う
root.style.getPropertyValue("--accent") が読むのは、style 属性に書かれた値だけです。スタイルシートの :root に書いた値は、style 属性にはないので空の文字列でした。CSS のどこで決まった値でも読みたいときは、getComputedStyle(要素).getPropertyValue("--accent") を使います。こちらは "#00c8e8" を返しました。
返ってくるのは、書いたままの文字列です。#00c8e8 が rgb(...) に直されることはなく、--gap: 12px は "12px" という文字列でした。数として使うなら、parseFloat() などで変換します。
style["–accent"] では変えられない
root.style["--accent"] = "red" と書いても、値は入りませんでした。getPropertyValue() は空の文字列で、箱の色も変わりません。また、setProperty("accent", "red") のように -- を付け忘れた場合も、style 属性には何も書かれませんでした。カスタムプロパティは、setProperty() に -- 付きの名前を渡して変えます。
数を入れて、単位は CSS で付ける
setProperty("--num", 30) のように数を渡すと、文字列の "30" として入りました。単位を付けるときは、CSS の側で calc() を使います。
.ok { padding-top: calc(var(--num) * 1px); } /* 30px */
.ng { padding-top: 5px; padding-top: var(--num)px; } /* 0px */
calc(var(--num) * 1px) は 30px になりました。var(--num)px のように後ろに単位を続けて書いた行は、30px にならず、前の行の 5px にも戻らず、padding-top の初期値の 0px でした。上で見た「値が合わない」場合と同じ結果です。
テーマの切り替えのように、色を場面に合わせて入れ替える例は、別の記事「CSSで、ダークモードに合わせて色を切り替える方法」と「Reactで、サイトの色をユーザーが選べるようにする方法」で扱っています。





