CSS custom properties

Quick reference for CSS custom properties: var() and its fallback, inheritance, invalid at computed-value time, and a short note on @property registration.

Custom properties are author-defined properties whose names start with --. They inherit by default. Their specified value is substituted with var(--name) or var(--name, fallback). The Colors page already notes that currentColor is not a custom property; this page is the --* and var() syntax, not a second color tutorial.

The fallback argument is used only when the referenced custom property is missing or is the guaranteed-invalid value. If the variable is defined but the substituted result is invalid for the target property, the fallback is not used. The declaration is then invalid at computed-value time and the property falls back to inheritance or to its initial value.

Examples are complete HTML and CSS fragments. They were parsed with PostCSS and a selector AST parser for syntax and structure. They were not rendered in a browser here, and this is not a visual or computed-value test.

Official sources: MDN and the CSS specification. Fragments were checked with PostCSS 8 for syntax and structure. That is not a CSS conformance suite, and this is not a browser render or visual test.

CSS reference catalog → · CSS tutorial overview →

var() fallback is not a general error rescue

var(--brand, red) uses red only when --brand is not defined, or when its value is the guaranteed-invalid value. A defined --oops: 8px used as color: var(--oops, #0B5853) substitutes 8px. That is not a missing variable, so the fallback color is not chosen. color then becomes invalid at computed-value time and, for an inherited property, takes the inherited color (or the initial color if there is nothing to inherit).

Custom properties inherit as specified values, which is why a child can read --brand from :root. You can assign a new --brand on a subtree to override the inherited one. Using the same name for unrelated types in one tree makes IACVT bugs harder to see.

Syntax or propertyInitial / defaultInheritedApplies toNotes
--*guaranteed-invalid valueyes (unless registered otherwise)all elementsA custom property. The name must start with two dashes. The unregistered initial value is the guaranteed-invalid value, which makes var() use its fallback.
var(--name)———Substitute the custom property’s value. If the name is missing or guaranteed-invalid, the declaration is invalid at computed-value time unless a fallback is provided.
var(--name, fallback)———The fallback is used only when the custom property is missing or guaranteed-invalid. It is not used merely because the substituted value is the wrong type for the surrounding property.

A defined but unusable value does not trigger the var() fallback

.ok { color: var(--brand, red); }
.missing { color: var(--undefined, #0B5853); }
.wrong { --oops: 8px; color: var(--oops, #0B5853); }

The first rule can use --brand. The second uses the fallback because the name is missing. The third keeps 8px as the substitution, so the #0B5853 fallback is not a rescue.

  • This checker confirms the declared var() forms. It does not compute the cascaded color, so the IACVT outcome is explained in the text rather than treated as a measured pixel color.
html
<p class="ok">Defined variable</p>
<p class="missing">Missing variable</p>
<p class="wrong">Defined length used as a color</p>
<style>
:root { --brand: #0B5853; }
.ok, .missing, .wrong { font-family: sans-serif; }
.ok { color: var(--brand, red); }
.missing { color: var(--undefined, #0B5853); }
.wrong { --oops: 8px; color: var(--oops, #0B5853); }
</style>

What this markup means

On :root, --brand is a color, so var(--brand, red) substitutes #0B5853 and the red fallback is unused. var(--undefined, #0B5853) has no such custom property, so the fallback is used. --oops is defined as 8px; color: var(--oops, #0B5853) therefore becomes color: 8px. The fallback is skipped because the variable exists. The color declaration is then invalid at computed-value time and does not snap to #0B5853 via var().

Related: Colors (currentColor is not a custom property)

MDN documentation → · CSS specification →

@property registration, briefly

@property --accent { syntax: "<color>"; inherits: false; initial-value: #0B5853; } registers a custom property: it gets a syntax, an inheritance flag, and a real initial value instead of the guaranteed-invalid value. That can catch type mistakes earlier than an unregistered variable.

The at-rule is a progressive addition. Engines that do not implement @property ignore the rule; an unregistered --accent still works as an ordinary inheriting custom property with a guaranteed-invalid initial value. This page does not treat @property as universally available, and the example is not a browser-support matrix.

Syntax or propertyInitial / defaultInheritedApplies toNotes
@property——stylesheet at-ruleRegisters a custom property. Descriptors are syntax, inherits, and initial-value. Initial-value must be valid for the given syntax.

A registered property has syntax and an initial value

@property --accent {
  syntax: "<color>";
  inherits: false;
  initial-value: #0B5853;
}

This registers --accent as a non-inheriting color with a defined initial value. Older engines that skip @property still see later var(--accent) as an unregistered variable.

  • inherits: false is the difference from the unregistered default. Whether a given browser honours the at-rule is not measured here.
html
<p class="swatch">Accent text</p>
<style>
@property --accent {
  syntax: "<color>";
  inherits: false;
  initial-value: #0B5853;
}
.swatch { font-family: sans-serif; color: var(--accent); }
</style>

What this markup means

The @property rule names --accent, restricts it to the <color> syntax, turns off inheritance, and gives it the initial value #0B5853. The paragraph then uses var(--accent). If the at-rule is ignored, --accent is just an unregistered custom property and the same var() still parses; what changes is inheritance and the initial value. That compatibility difference is why registration is described as progressive, not as a requirement for using custom properties at all.

Related: MDN @property

MDN documentation → · CSS specification →