Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / CSS

@property — typed custom-property registration

The @property rule registers a custom property with a value type, inheritance behavior, and an initial value.

Version: CSS modules; structured CSSWG indexes reconciled with pinned MDN BCD; Chromium 152 scope gate, per-example verification still required

Syntax

@property <custom-property-name># {
  <declaration-list>
} | @property <custom-property-name> <css-type>? [ : <declaration-value>? ]? ;

The block form @property <custom-property-name># { <declaration-list> } can register one name or a comma-separated list of names. The syntax descriptor defaults to *, inherits defaults to true, and an omitted initial-value leaves the guaranteed-invalid initial value. The specification also allows the statement shorthand @property <custom-property-name> <css-type>? [ : <declaration-value>? ]? ;, which always keeps the default inheritance behavior.

The registered type is checked at computed-value time, not when the declaration is first parsed. A supplied initial value must match the grammar; unknown descriptors are ignored. If several rules register the same name, the last valid rule in stylesheet order wins, while a registration made through CSS.registerProperty() takes precedence over all of them.

Registration enables meaningful interpolation of numbers, colors, or lengths and explicit inheritance for a component API. The example registers --tone as <color> without inheritance. The mismatching 10px passes declaration parsing but fails at computed-value time, so the child receives the green initial value; a valid blue color remains blue. The CSSPropertyRule object confirms the registered name and inheritance flag.

Examples

const style = document.createElement('style');
style.textContent = `@property --tone { syntax: "<color>"; inherits: false; initial-value: rgb(0 128 0); }
.parent { --tone: red; }
.invalid { --tone: 10px; color: var(--tone); }
.valid { --tone: blue; color: var(--tone); }`;
document.head.append(style);
const parent = document.createElement('div');
parent.className = 'parent';
parent.innerHTML = '<span class="invalid">invalid</span><span class="valid">valid</span>';
document.body.append(parent);
const invalid = getComputedStyle(parent.children[0]);
const valid = getComputedStyle(parent.children[1]);
const rule = style.sheet.cssRules[0];
console.log('rule=' + rule.constructor.name + '; name=' + rule.name + '; invalid=' + invalid.getPropertyValue('--tone').trim() + '; valid=' + valid.getPropertyValue('--tone').trim() + '; inherits=' + rule.inherits);

Result

rule=CSSPropertyRule; name=--tone; invalid=rgb(0, 128, 0); valid=rgb(0, 0, 255); inherits=false

The @property rule registers a custom property with a value type, inheritance behavior, and an initial value.

Sources