【CSS】@property でカスタムプロパティを宣言しよう

@property とはCSSカスタムプロパティ（例：--main-color のような変数）に型・初期値・継承可否を与えて“登録”できる CSSのアットルールです。

型や初期値が定義でき、無効値による崩れ防止や、フォールバック（var(–size, 100%) の値100%の箇所）を毎回書かなくても良くなります。

2025年現在、主要なブラウザには全て対応していますので安心して利用してください。

Can I use ?

カスタムプロパティって何？という方はまずは下記の記事をご確認ください。

【CSS】カスタムプロパティ（変数）とは？使い方やSassとの違いを徹底解説

基本の書き方とサンプル
各オプションについて
オプションのサンプル事例
- 継承trueで設定した場合のサンプル
- 型以外の値をセットした場合のサンプル
@propertyでカスタムプロパティを宣言するメリット
- フォールバックの記述が不要に
- アニメーションの一括変更が可能に
syntaxの指定方法について
最後に

基本の書き方とサンプル

下記は基本のサンプルになります。

@propertyを使って、カスタムプロパティ（ --brand-color という変数名）を宣言しています。

@property --brand-color {
    syntax: "<color>";
    inherits: true;
    initial-value: #0a84ff;
}

次に@propertyで宣言したカスタムプロパティ（--brand-color）を.buttonの色に設定し、hover時に--brand-colorの色を変更してtransition を使って状態を変化させています。


.button {
    color: var(--brand-color);
    border-color: var(--brand-color);
    transition: --brand-color .2s ease;
}
.button:hover { --brand-color: #ff3366; } /* #ff3366に変更 */

以下はサンプルコードのデモです。

各オプションについて

syntaxは型の宣言

この変数に許可する“値の型”を宣言します。

例: 色<color>, サイズ<length>, 数値<number>, 角度<angle> など。

アスタリスク * で型を指定しないことも可能ですが、できるだけ型指定しましょう。

アスタリスク *	型の指定なし
色 `<color>`	#hex、rgb()、hsl()も可
数値 `<number>`	単位なしの数（小数OK）。
角度 `<angle>`	deg / turn / rad / grad。
長さ `<length>`	px, em, rem, vw…。%は不可。

この他にも多くの型があります。詳しくは下記を参照ください。

https://drafts.css-houdini.org/css-properties-values-api/#supported-names

inheritsは継承の有無

継承の有無を決めます。

true：親の値を子要素が引き継ぐ（テーマカラーなど全体に波及させたい場合など）

false：継承せず、未指定の要素は initial-value を使う

initial-valueはデフォルト値

初期値。未指定時の既定値です。

また、syntaxで許可した型以外の値が入るとこの値が使われます。
inherits: true でも型外の場合はinitial-valueに戻ります（親の値は使われません）

オプションのサンプル事例

継承trueで設定した場合のサンプル

parent（親）で設定したcolor（#ff3366）がchild（子）にも継承されています。

この場合、継承をfalseで設定した場合は、childはinitial-value（#0a84ff）になります。

html

<div class="parent">
    <p class="child">継承されるテキスト</p>
</div>

css

@property --brand {
    syntax: "<color>";
    inherits: true;
    initial-value: #0a84ff;
}
.parent {
    --brand: #ff3366;  /* 親でセット → 子にも伝わる */
}
.child {
    color: var(--brand); /* 子のcolorは #ff3366 になる */
    border: 1px solid var(--brand);
}

継承されるテキスト

型以外の値をセットした場合のサンプル

継承をtrueにして、parent（親）で設定したcolor（#ff3366）がchild（子）にも継承されています。

さらに、child（子）で新たにカスタムプロパティの値をcolor型以外の「50%」に変更しています。

型以外の値がセットされたため、initial-valueに設定された初期値の（#0a84ff;）がセットされます。

html

<div class="parent">
    <p class="child">継承されるテキスト</p>
</div>

css

@property --brand {
    syntax: "<color>";
    inherits: true;
    initial-value: #0a84ff;
}
.parent {
    --brand: #ff3366;  /* 親でセット → 子にも伝わる */
}
.child {
    --brand: 50%;  /* 子に"50%"を設定 */
    color: var(--brand); /* 子のcolorは #0a84ff になる */
    border: 1px solid var(--brand);
}

継承されるテキスト

@propertyでカスタムプロパティを宣言するメリット

フォールバックの記述が不要に

初期値(initial-value)が設定されますので、毎回のフォールバックの記述が不要になります。

padding: var(--space, 12px);

　↓

padding: var(--space);

アニメーションの一括変更が可能に

今回のサンプルでは、@propertyが未登録だとtransition: color, border-color … を列挙する必要がありますが、（全体ならallか省略（指定なし）でも可能ですが）transition: --brand-color .2s ease;これだけでそのカスタムプロパティを参照する全てのプロパティが一括で変更が可能になります。

.button {
    color: var(--brand-color);
    border-color: var(--brand-color);
    transition: color .2s ease,  border-color .2s ease;
}

　↓

.button {
    color: var(--brand-color);
    border-color: var(--brand-color);
    transition: --brand-color .2s ease;
}

@property は“登録”なので 1 度だけ宣言するのが原則です。（同名を再登録しても無視されます）。
インラインstyle属性には書けません（スタイルシート内で宣言）。
JavaScript の registerProperty() でも登録できます。

syntaxの指定方法について

syntax（型）には複数の型が宣言できます。

また、宣言時に記号と一緒に使うことで色々な値の指定が可能になります。

（+）指定で、スペース区切りの値を複数指定できます。

@property --gradient-color {
  syntax: "<color>+"; /* 最後に+をつける */
  inherits: false;
  initial-value: #0a84ff #ff3366;
}
.box {
  background: linear-gradient(90deg, var(--gradient-color));
           /* linear-gradient(90deg, #0a84ff #ff3366 ); と同じ */
}

（#）指定で、カンマ区切りで複数指定できます。

@property --font-stack {
  syntax: "<string>#";
  inherits: false;
  initial-value: "Hiragino Sans", "Meiryo", sans-serif;
}
.text {
  font-family: var(--font-stack);
}

（ | ）で区切って任意のルールが適用できます。

/* 
　「色 or none」を許容 
   --main-color: #ffffff; も --main-color: none;も可能
*/
@property --main-color {
  syntax: "<color> | none";
  inherits: false;
  initial-value: none;
}

/*
   「長さ・パーセント・auto」全部許可
   --height: 200px;   ← px指定OK 
   --height: 80%;     ← パーセントOK
   --height: auto;    ← 自動 
*/
@property --width {
  syntax: "<length> | <percentage> | auto";
  inherits: false;
  initial-value: auto;
}

/* 
　上記はこのような指定もできます
*/
@property --height {
  syntax: "<length-percentage> | auto";
  inherits: false;
  initial-value: auto;
}