CSSFunctionDeclarations
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
The CSSFunctionDeclarations interface of the CSS Object Model represents a consecutive run of CSS declarations included within a @function body.
This can include CSS custom properties, and the value of the results descriptor inside the @function body, but it doesn't include blocks such as @media at-rules that may be included. Such a block, included in the middle of a set of declarations, would cause the body contents to be broken up into separate CSSFunctionDeclarations objects, as seen in our Multiple CSSFunctionDeclarations demo.
Instance properties
This interface also inherits properties from CSSRule.
CSSFunctionDeclarations.styleRead only Experimental-
Returns a
CSSFunctionDescriptorsobject representing the descriptors available in a@functionbody.
Examples
Basic CSSFunctionDeclarations usage
In this example, we define a CSS custom function and then access its declarations using the CSSOM.
CSS
Our CSS defines a custom function using the @function at-rule. The function is called --lighter(), and outputs a lightened version of an input color. --lighter() accepts two parameters, a <color> and a <number>. It returns an oklch() color created using relative color syntax; the input color is transformed into an oklch() color and its lightness channel is increased by the input number.
@function --lighter(--color <color>, --lightness-adjust <number>: 0.2) returns
<color> {
--someVar: 100;
result: oklch(from var(--color) calc(l + var(--lightness-adjust)) c h);
}
We've also included a local custom property inside the function, --someVar, which isn't used, but illustrates what happens when multiple declarations are available continuously inside the @function body.
JavaScript
Our script starts by getting a reference to the stylesheet attached to our document using HTMLStyleElement.sheet, then getting a reference to the only rule in the stylesheet, the CSSFunctionRule — via CSSStylesheet.cssRules.
We then access the CSSFunctionDeclarations object representing the only continuous run of declarations inside the function using cssRules[0], access its descriptor's information using CSSFunctionDeclarations.style, and then access the descriptor length and style information. All of this information is logged to the console.
// Get a CSSFunctionRule
const cssFunc = document.getElementById("css-output").sheet.cssRules[0];
// Accessing CSSFunctionDeclarations and CSSFunctionDescriptors
console.log(cssFunc.cssRules[0]); // CSSFunctionDeclarations
console.log(cssFunc.cssRules[0].style); // CSSFunctionDescriptors
console.log(cssFunc.cssRules[0].style.length);
console.log(cssFunc.cssRules[0].style.result);
Most notably:
- The
lengthproperty is equal to2, as there are two parts to the descriptor's text (--someVar: 100;andresult: oklch(from var(--color) calc(l + var(--lightness-adjust)) c h);). - The
resultproperty is equal to the@functionbody'sresultdescriptor, which isoklch(from var(--color) calc(l + var(--lightness-adjust)) c h).
Multiple CSSFunctionDeclarations
In this example, we show how a @media at-rule inserted in the middle of a set of declarations causes two CSSFunctionDeclarations objects to be generated.
CSS
Our CSS shows a @function example taken from the specification, --bar(), which doesn't do much, but features a set of declarations separated by a @media block.
@function --bar() {
--x: 42;
result: var(--y);
@media (width > 1000px) {
/* ... */
}
--y: var(--x);
}
JavaScript
Our script starts by getting a reference to the stylesheet attached to our document via HTMLStyleElement.sheet, then getting a reference to the only rule in the stylesheet, the CSSFunctionRule — via CSSStylesheet.cssRules.
We then access the CSSGroupingRule.cssRules, logging its value to the console. This returns a CSSRuleList object containing three objects:
- A
CSSFunctionDeclarationsobject representing the--x: 42;result: var(--y);portion. - A
CSSMediaRuleobject representing the@mediaat-rule. - A second
CSSFunctionDeclarationsobject representing the--y: var(--x);portion.
// Get a CSSFunctionRule
const cssFunc = document.getElementById("css-output").sheet.cssRules[0];
// Accessing both CSSFunctionDeclarations
console.log(cssFunc.cssRules);
We then log a few details of each CSSFunctionDeclarations object to the console — the object itself, the CSSFunctionDescriptors object contained in its style property, and the CSSFunctionDescriptors.result property.
console.log(cssFunc.cssRules[0]); // First CSSFunctionDeclarations
console.log(cssFunc.cssRules[0].style); // CSSFunctionDescriptors
console.log(cssFunc.cssRules[0].style.result);
console.log(cssFunc.cssRules[2]); // Second CSSFunctionDeclarations
console.log(cssFunc.cssRules[2].style); // CSSFunctionDescriptors
console.log(cssFunc.cssRules[2].style.result);
In the second case, result returns an empty string, because the second declarations portion does not contain a result descriptor.
Specifications
| Specification |
|---|
| CSS Functions and Mixins Module # the-function-declarations-interface |
Browser compatibility
Loading…