CSSFunctionDeclarations
CSSOM
CSSOM
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.style
- : Returns a CSSFunctionDescriptors object representing the descriptors available in a @function body.
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.
```css live-sample___cssfunctiondeclarations-basics
@function --lighter(--color
We've also included a local [custom property](/docs/Web/CSS/Guides/Cascading_variables/Using_custom_properties) 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.
```js live-sample___cssfunctiondeclarations-basics
// 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.
```css live-sample___multiple-cssfunctiondeclarations @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 `CSSFunctionDeclarations` object representing the `--x: 42;result: var(--y);` portion.
- A CSSMediaRule object representing the `@media` at-rule.
- A second `CSSFunctionDeclarations` object representing the `--y: var(--x);` portion.
```js live-sample___multiple-cssfunctiondeclarations
// 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.
```js live-sample___multiple-cssfunctiondeclarations 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
Browser compatibility
See also
- @function
- CSSFunctionRule
- CSSFunctionDescriptors