Getting Started with CSS @property Rule

The CSS @property is a powerful feature that brings more control and flexibility to custom properties, also known as CSS variables.

It is introduced as part of the CSS Houdini project, which is designed to provide developers with deeper access to the browser’s rendering engine. The @property rule allows you to define custom properties with specific types, default values, and even the capability to animate CSS properties.

In this article, we’ll explore what the @property rule is, why it’s useful, and how you can leverage it in your web projects.

What is @property for?

CSS custom properties, also known as CSS variables, have made styles more reusable. It allows you to define a value once and use it throughout your stylesheet.

However, one limitation has been the inability to specify a property’s type or set default values directly in CSS. This means any value can be assigned to a custom property, which can lead to unexpected results and make it harder to maintain your styles in some situations.

This is where the @property rule comes in. It allows you to set a default value, provides a fallback value that will be used if the custom property is not explicitly set, enables custom property animation, and defines a type for a custom property.

This ensures that a variable can only accept a specific data type, such as a length, color, or number.

The type of the property is defined with the syntax property. It accepts a string value defining the CSS type value, as follows:

Example

Let’s say we have a button component. We’d like to define some defaults on this component. Traditionally, we could use custom properties to define the background color and border radius of the button component, like so:

.button {
  background-color: #fff;
  border-radius: 8px;
}

Or, use CSS variables to define the values once and reuse them throughout the stylesheet:

:root {
  --button-bg: #fff;
  --button-rounded: 8px;
}

But, what if we want to ensure that the background color is always a valid color value, and the border radius is always a valid length value?

We can use the @property rule to define the type of these custom properties and set default values.

To do so, we could create a couple of custom properties defined with the following options in the @property rule:

@property --button-bg {
  syntax: '<color>';
  initial-value: #0D74CE;
  inherits: false;
}
@property --button-rounded {
  syntax: '<length>';
  initial-value: 8px;
  inherits: false;
}

In this example, we have two custom properties defining the background color and border radius of the button component.

We use the syntax property to define the type of the custom property, while the initial-value property sets the default value.

We also use the inherits property to specify whether the custom property inherits its value from its parent element, in which case we set them all to false to avoid inheritance.

Once they are set, we can now use these custom properties in our styles, like so:

.button {
  background-color: var(--button-bg);
  border-radius: var(--button-rounded);
}

See the Pen CSS @property by HONGKIAT (@hkdc) on CodePen.

Wrapping up

The CSS @property rule brings a significant step forward to CSS custom properties, or CSS variables. All major and latest browsers already support the CSS @property rule.

To sum up, the CSS @property rule is a powerful feature and a great addition to the CSS language that can help you write more maintainable and type-safe stylesheets. If you haven’t already, give it a try in your next project!