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.

CSSRule CSSFunctionDeclarations

Instance properties

This interface also inherits properties from CSSRule.

CSSFunctionDeclarations.style Read only

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
@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.

js
// 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 length property is equal to 2, as there are two parts to the descriptor's text (--someVar: 100; and result: oklch(from var(--color) calc(l + var(--lightness-adjust)) c h);).
The result property is equal to the @function body's result descriptor, which is oklch(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
@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
// 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
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.