CSS - @property

The @property CSS at-rule, part of the CSS Houdini APIs, allows developers to explicitly define custom properties.

The @property rule:

  • Provides features such as property type checking, constraints, setting default values, and specifying inheritance behavior for CSS custom properties.

  • Allows you to register custom properties in stylesheets without using JavaScript.

  • Create registered custom properties, similar to calling registerProperty() with equivalent parameters in JavaScript.

Some points to remeber when using @property CSS at-rule:

  • A valid @property rule means registering a custom property with the property name derived from the serialization in the rule's prelude.

  • @property rules must contain both a syntax and inherits descriptor. If either is missing, the rule is invalid and ignored.

  • The initial value descriptor is optional only for universal syntax definition, otherwise, it is required. If it is missing, the entire rule is invalid and ignored.

  • Unknown descriptors within a @property rule are ignored and considered invalid, but they do not invalidate the entire @property rule.

Syntax

@property <custom-property-name> { <declaration-list> }

CSS @property - Using Custom Property

The following example demonstrates the @property without using javascript.

<html>
<head>
<style>
   @property --main-color {
      syntax: '<color>';
      inital-value: black;
      inherits: true;
   }
   .box {
      --main-color: red;
      background-color: var(--main-color);
      width: 200px;
      height: 200px;
      margin: 50px auto;
      display: flex;
      align-items: center;
      justify-content: center;
      color: white;
      font-size: 24px;
      font-weight: bold;
      text-align: center;
   }
</style>
</head>
<body>
   <div class="box">
      <p>CSS At-Rules @property</p>
   </div>
</body>
</html>

CSS @property - Using Custom Property And registerProperty()

The following example demonstrates the usage of @property and registerProperty().

  • In the following example, CSS @property defines a custom property called --item-size and specifies that it accepts and inherits percentage values and starts with an initial value of 40%.

  • The window.CSS.registerProperty in JavaScript dynamically registers a new custom property named --item-color, sets its syntax to <color>, specifies that it is not inherited, and assigns it an initial value of peachpuff.

<html>
<head>
<style>
   @property --item-size {
      syntax: "<percentage>";
      inherits: true;
      initial-value: 40%;
   }
   /* set custom property values on parent */
   .container {
      display: flex;
      height: 100px;
      border: 3px dotted black;
      --item-size: 50%;
      --item-color: tomato;
      --item-border: 5px solid green;
   }
   /* use custom properties to set item size and background color */
   .item {
      width: var(--item-size);
      height: var(--item-size);
      border: var(--item-border);
      background-color: var(--item-color);
   }
   /* set custom property values on element itself */
   .second {
      --item-size: initial;
      --item-color: inherit;
   }
</style>
</head>
<body>
   <div class="container">
      <div class="item">First Item</div>
      <div class="item">Second Item</div>      
   </div>
<script>
   window.CSS.registerProperty({
   name: "--item-color",
   syntax: "<color>",
   inherits: false,
   initialValue: "peachpuff",
   });
</script>
</body>
</html>

Descriptors

Descriptors Explaination
syntax Explains the permissible syntax for the property.
inherit Determines if the custom property registration defined by @property inherits by default.
initial-value Defines the property's initial value.
Advertisements