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.

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

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

// 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

Browser compatibility

See also

• @function
• CSSFunctionRule
• CSSFunctionDescriptors