Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / CSS

CSS custom properties: --*

Custom properties store values under names beginning with --. They participate in the cascade, inherit by default, and let var() substitute their values into other property declarations.

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

Syntax

--name: <declaration-value>?;
property: var(--name, fallback);

--* denotes the custom-property family, not a literal declaration name. Use a valid identifier beginning with --, such as --size; -- alone is reserved. Names are case-sensitive: --size and --Size are different properties.

Unregistered custom properties participate in the cascade and inherit. They store CSS tokens, not necessarily a valid value for the consuming property. var(--size, 20px) substitutes --size; its fallback applies when that property has the guaranteed-invalid value, including when no declaration supplies it. It does not repair an existing value that is unsuitable for the consuming property: --size: red will not trigger the fallback for width.

An unregistered property's initial value is guaranteed-invalid; initial restores it. By contrast, the empty declaration --size:; is a valid empty value. Cyclic references produce invalid values. In the example, the first rectangle inherits 40px, while the second uses the 20px fallback after applying initial.

Examples

<!doctype html>
<meta charset="utf-8">
<title>Custom property inheritance</title>
<style>
  .group { --size: 40px; }
  .box {
    width: var(--size, 20px);
    height: 20px;
    background: black;
    margin-bottom: 4px;
  }
  .reset { --size: initial; }
</style>
<div class="group">
  <div class="box"></div>
  <div class="box reset"></div>
</div>

Result

.box: width = 40px
.box.reset: width = 20px

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources