{"id":72701,"date":"2024-09-02T18:00:09","date_gmt":"2024-09-02T10:00:09","guid":{"rendered":"https:\/\/www.hongkiat.com\/blog\/?p=72701"},"modified":"2024-10-29T19:50:51","modified_gmt":"2024-10-29T11:50:51","slug":"css-property-rule","status":"publish","type":"post","link":"https:\/\/www.hongkiat.com\/blog\/css-property-rule\/","title":{"rendered":"Getting Started with CSS @property Rule"},"content":{"rendered":"

The CSS @property<\/code> is a powerful feature that brings more control and flexibility to custom properties, also known as CSS variables<\/a>.<\/p>\n

It is introduced as part of the CSS Houdini<\/a> project, which is designed to provide developers with deeper access to the browser\u2019s rendering engine. The @property<\/code> rule allows you to define custom properties with specific types, default values, and even the capability to animate CSS properties<\/a>.<\/p>\n

In this article, we\u2019ll explore what the @property<\/code> rule is, why it\u2019s useful, and how you can leverage it in your web projects.<\/p>\n

What is @property<\/code> for?<\/h2>\n

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.<\/p>\n

However, one limitation has been the inability to specify a property\u2019s 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.<\/p>\n

This is where the @property<\/code> 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.<\/p>\n

This ensures that a variable can only accept a specific data type, such as a length, color, or number.<\/p>\n

The type of the property is defined with the syntax<\/code> property. It accepts a string value defining the CSS type value, as follows:<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Type<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
<length><\/code><\/td>\nAny valid <length><\/code> values e.g., 10px, 2em, 50%, 3rem<\/td>\n<\/tr>\n
<number><\/code><\/td>\nAny valid <number><\/code> values e.g., 1, 0.5, -3, 100<\/td>\n<\/tr>\n
<percentage><\/code><\/td>\nAny valid <percentage><\/code> values e.g., 50%, 100%, 25%<\/td>\n<\/tr>\n
<length-percentage><\/code><\/td>\nAny valid <length-percentage><\/code> values e.g., 10px, 50%, 2em, 75%<\/td>\n<\/tr>\n
<color><\/code><\/td>\nAny valid <color><\/code> values e.g., #ff0000, rgb(255, 0, 0), rgba(255, 0, 0, 0.5), blue<\/td>\n<\/tr>\n
<image><\/code><\/td>\nAny valid <image><\/code> values e.g., url(image.jpg), linear-gradient(to right, red, blue)<\/td>\n<\/tr>\n
<url><\/code><\/td>\nAny valid url()<\/code> values e.g., url(\u2018https:\/\/example.com\/image.jpg\u2019)<\/td>\n<\/tr>\n
<integer><\/code><\/td>\nAny valid <integer><\/code> values e.g., 1, -10, 42<\/td>\n<\/tr>\n
<angle><\/code><\/td>\nAny valid <angle><\/code> values e.g., 45deg, 0.5turn, 1rad<\/td>\n<\/tr>\n
<time><\/code><\/td>\nAny valid <time><\/code> values e.g., 1s, 500ms, 0.75s<\/td>\n<\/tr>\n
<resolution><\/code><\/td>\nAny valid <resolution><\/code> values e.g., 300dpi, 2dppx<\/td>\n<\/tr>\n
<transform-function><\/code><\/td>\nAny valid <transform-function><\/code> values e.g., rotate(45deg), scale(1.5), translateX(100px)<\/td>\n<\/tr>\n
<custom-ident><\/code><\/td>\nAny valid <custom-ident><\/code> values e.g., \u2013my-variable, custom-identifier<\/td>\n<\/tr>\n
<transform-list><\/code><\/td>\nA list of valid <transform-function><\/code> values e.g., rotate(45deg) scale(1.5) translateX(100px)<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Example<\/h2>\n

Let\u2019s say we have a button component. We\u2019d 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:<\/p>\n

\r\n.button {\r\n  background-color: #fff;\r\n  border-radius: 8px;\r\n}\r\n<\/pre>\n
Or, use CSS variables to define the values once and reuse them throughout the stylesheet:<\/p>\n
\r\n:root {\r\n  --button-bg: #fff;\r\n  --button-rounded: 8px;\r\n}\r\n<\/pre>\n
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?<\/p>\n
We can use the @property<\/code> rule to define the type of these custom properties and set default values.<\/p>\n
To do so, we could create a couple of custom properties defined with the following options in the @property<\/code> rule:<\/p>\n
\r\n@property --button-bg {\r\n  syntax: '<color>';\r\n  initial-value: #0D74CE;\r\n  inherits: false;\r\n}\r\n@property --button-rounded {\r\n  syntax: '<length>';\r\n  initial-value: 8px;\r\n  inherits: false;\r\n}\r\n<\/pre>\n
In this example, we have two custom properties defining the background color and border radius of the button component.<\/p>\n
We use the syntax<\/code> property to define the type of the custom property, while the initial-value<\/code> property sets the default value.<\/p>\n
We also use the inherits<\/code> 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.<\/p>\n
Once they are set, we can now use these custom properties in our styles, like so:<\/p>\n
\r\n.button {\r\n  background-color: var(--button-bg);\r\n  border-radius: var(--button-rounded);\r\n}\r\n<\/pre>\n
 See the Pen  CSS @property<\/a> by HONGKIAT (@hkdc<\/a>)\n  on CodePen<\/a>.<\/span><\/p>\n