CSS Custom Properties provides the ability to define and re-use variables that participate in the runtime cascade.
CSS Custom Properties are defined using the
--* property syntax, and accessed using the
var(--*) CSS function.
To learn more about this language feature, check out the following resources
- MDN - Custom properties
- MDN - Using CSS custom properties
- Smashing Magazine - It's Time To Start Using CSS Custom Properties
Stylable variables and CSS custom properties offer different capabilities, and as such serve different use-cases.
Stylable variables exist only in your source code, and get replaced during transpilation to the final target code. They serve well for calculations that are not supported by native CSS, reducing code repetition, increasing readability and can benefit any static theme or styling without incurring any runtime performance cost.
CSS custom properties on the other hand do incur a small runtime cost, but offer the ability to override their values during runtime, allowing dynamic styling through Stylable.
Stylable automatically scopes any CSS custom property found in the stylesheet. It does so by generating a unique namespace for the stylesheet (similar to how classes are scoped), and replaces the variable with its scoped counterpart.
Due to the fact Stylable provides scoping to CSS variables, it also provides the ability to import CSS variables defined in another stylesheet.
Override any variable by redefining its value using an inline style attribute.
Stylable supports the @property at-rule, it scope the CSS variable and provide extra configuration at runtime:
In cases where you have no control over the name of the CSS variable used, use the
@st-global-custom-property directive to define CSS variables that will not be scoped, and will maintain their exact given name.
This is mostly useful when working with 3rd-party libraries, where you only attempt to affect it externally.
Accessing any globally defined variable on the stylesheet will return its global name (un-scoped).