CSS @property Rule

The CSS @property Rule

Custom CSS properties (CSS variables) can be defined right in your stylesheet with the @property rule, and no JavaScript is involved.

The rule gives you three controls: a data type, a default value, and whether the property inherits from parent elements.

Syntax of @property

Here --myColor is created as a color property. Inheritance is on, and lightgray is its default value.

styles.css 
@property --myColor {
  syntax: "<color>";
  inherits: true;
  initial-value: lightgray;
}

Using the custom property

To insert the custom property's value, call the CSS var() function:

styles.css 
body {
  background-color: var(--myColor);
}

Benefits of Using @property

Why use @property? It brings three advantages:

  • Data type checking: Declaring a type for the custom property, such as <number>, <color>, <length>, etc., is mandatory. That guards against errors and keeps the property used correctly.
  • Set default value: A default value for the custom property is mandatory too. Should an invalid value be assigned later, the browser falls back to it.
  • Set inheritance behavior: You also have to state whether the custom property inherits from parent elements, so inheritance is entirely under your control.

CSS @property Example

Two custom properties are defined here, --my-bg-color and --my-txt-color, and the div takes its background color and text color from them.

Example

Prompt
Create a page that uses CSS @property to define two custom properties: --my-bg-color (lightgray) and --my-txt-color (darkblue), both as color types with inheritance. Apply them to a div (300x150px, 15px padding) using var().
Output: complete HTML page

Another @property Example

The <div> element starts with the custom property's default. Classes .fresh and .nature then override it, each with its own color.

Example

Prompt
Create a page using CSS @property to define --my-bg-color as a color with initial-value lightgray and inherits true. Show three divs (300x150px, 15px padding): one with the default color, one with class "fresh" overriding to #ff6347, and one with class "nature" overriding to rgb(120, 180, 30).
Output: complete HTML page

Avoid Error with Type Checking and Fallback Value

Class .nature assigns an integer to the custom property here. An integer is not a valid color, so the browser falls back to the initial-value (lightgray).

Example

Prompt
Create a page using CSS @property to define --my-bg-color as a color with initial-value lightgray and inherits true. Show three divs (300x150px, 15px padding): default, class "fresh" set to #ff6347, and class "nature" set to the invalid value 2 (an integer). The browser should fall back to lightgray for the invalid one.
Output: complete HTML page

Use of the inherits Value

Whether a custom property takes values from parent elements is decided by the inherits descriptor.

inherits: false

Setting inherits to false cuts the custom property off from its parent elements' values. Child elements receive the initial value instead.

Prompt
Create a page using CSS @property to define --my-bg-color as a color with initial-value lightgray and inherits set to false. Set --my-bg-color to coral on the body. Show a child div (300x150px, 15px padding) that uses var(--my-bg-color) as background — since inherits is false, the div should get lightgray, not coral.
Output: complete HTML page

inherits: true

Setting inherits to true lets the custom property take on values from its parent elements.

Prompt
Create a page using CSS @property to define --my-bg-color as a color with initial-value lightgray and inherits set to true. Set --my-bg-color to coral on the body. Show a child div (300x150px, 15px padding) that uses var(--my-bg-color) as background — since inherits is true, the div should inherit coral from the body.
Output: complete HTML page

Create Smooth Animation with @property

Things that could not be animated before, gradients among them, become animatable with @property, which makes it especially powerful. Once color properties are registered this way, the browser knows how to interpolate them smoothly.

Example

A gradient's two custom color properties are defined here, then animated on hover:

Prompt
Create a page that uses CSS @property to define two color properties (--startColor: #EADEDB, --endColor: #BC70A4, both inherits false). Apply a linear-gradient using these properties to a div, and animate both colors on hover to create a smooth gradient transition that would not be possible without @property.
Output: complete HTML page