@property - CSS At-rule

Description of the @property at-rule.

The @property at-rule allows you to declare a custom property. In addition to defining it without a declaration (see var() ), @property lets you specify an initial value and inheritance for the custom property.

Example. Syntax without declaration:

The same example, declaration with @property:

Declaring custom properties makes it possible to use them in more places. In particular, declaring the data type allows the use of custom properties in animations.

The first example below uses an undeclared custom property (--angle1). You can see that the animation is choppy because the browser doesn't know what angle1 refers to.
In the second example, --angle2 is typed as an angle and its initial value is 0deg: the animation can run smoothly.

Custom properties return a computed value, which is also an optimization factor.

Also related to custom properties.

@property:

Defines a custom property, with its initial value, its syntax, and an indication of inheritance.

@function:

The @function at-rule defines a custom function, along with its parameters.

var() :

Retrieves the value of a custom property (variable).

Syntax of the syntax descriptor.

• @property --id { syntax: '<color>'; ... }

  Indicate the type of data accepted by the custom property. This descriptor is mandatory, otherwise the entire @property directive is invalid. It's a word between < > and in quotes (or double quotes) that can be:

  • <angle>: an angle value (followed by a CSS angle units, or a function that returns an angle like acos(), for example.
  • <color>: a color expressed in any of the syntaxes recognized by CSS, or a function that returns a color.
  • <custom-ident>: A custom username. Case sensitive.
  • <image>: an image or a function that returns an image.
  • <integer>: an integer, without a decimal point and without a unit.
  • <length>: a dimension, that is to say a number followed by one of CSS dimension units, or a function that returns a dimension.
  • <length-percentage>: a dimension or a percentage that resolves into a dimension.
  • <number>: a number without a unit.
  • <percentage>: a percentage, that is, a value followed by the % sign.
  • <resolution>: a value followed by a CSS units of resolution. Resolution units are mostly used in media queries.
  • <string>:A string of characters, that is to say a sequence of characters surrounded by apostrophes or quotation marks.
  • <time>: a numerical value followed by a CSS units of duration.
  • <transform-function>: a transformation function: rotate(), scale(), skew(), translate(), matrix(), or perspective(), as well as the 3D variants of these functions: rotateX(), rotateY(), rotateZ(), rotate3d(), scaleX(), scaleY(), scaleZ(), scale3d(), skewX(), skewY(), translateX(), translateY(), translateZ(), translate3d(), matrix3d();
  • <transform-list>: a list of transformation functions. Equivalent to <transform-function>+.
  • <url>: a URL defined by the url() or src() function.
  • *: any type of data.
• @property --id { syntax: '<color>+'; ... }

  The + sign indicates a series of values separated by a space.
  The * sign indicates a series of values separated by a comma.
  The | sign indicates multiple syntax options, which can accept any of the syntaxes separated by |.

  Example. To indicate a property that accepts an integer or a series of colors, write:

  @property --id { syntax: '<integer> | <color>+' ; ... }
• @property --id { syntax: 'auto | manual'; ... }

  Words not surrounded by < > indicate a property that accepts those words as values.

Syntax of the inherits descriptor.

• @property --id { inherits: true; ... }

  The inherits descriptor can only take one of two values: true or false.
  true means the property is inherited by default.
  false means the property is not inherited.

  This descriptor is mandatory, otherwise the entire @property directive is invalid.

Syntax of the initial-value descriptor.

• @property --id { initial-value: ...; ... }

  initial-value specifies the initial value of the custom property. It must of course conform to what is described in syntax.
  This descriptor is also required.

Examples of use of the @property at-rule.

Property not inherited by default.

The property has an initial value equal to red and is not inherited by default. In this example, we can see that the initial value is what's being used because the property, even though set on the section, doesn't "flow down" to the heading. You would have needed to set its value on the heading as well.

Property with default inheritance.

This time the property is inherited by default, its initial value is still red. This example shows that the value goes down to the h4 heading in section 2.

Definition of the type of data.

The properties defined with @property are also useful for animations, especially those that work with continuous data (colors, dimensions, numbers, etc.). If the browser doesn’t know the data type, it can’t perform a smooth animation. With @property, the browser knows what kind of data it’s dealing with (the syntax descriptor), so it’s able to carry out a smooth animation (example in section 4 below).

Browsers compatibility with the @property at-rule.

Custom properties are now well recognized by all major browsers.

1

Custom
properties

2

@property
at-rule

Estimated overall support.

96%

95%

Browsers on computers :

Mobile browsers :

Outdated or marginal browsers :

Internet Explorer

KaiOS Browser

Samsung Internet

Edge

Firefox

Androïd Brower

Chrome pour Androïd

Baidu Browser

QQ Browser

Safari

Safari sur IOS

Chrome

Opéra

Opéra Mobile

UC Browser pour Androïd

Firefox pour Androïd

Opéra mini

See Caniuse.com for more compatibility information.

Caniuse

Caniuse

Evolution of the @property at-rule.

• CSS Properties and Values API Level 1

  Regarding @property Definition of the @property at-rule that allows the definition of a custom property without using Javascript.
  

  March 26, 2024

  Working Draft.

  

  

  

See also, about custom properties.

Custom properties, also called variables, are described in the specification module CSS Properties and Values API.

• var() : Retrieves the value of a custom property (variable).