1. Introduction
This section is not normative.
Note: At this time, this specification only defines custom functions, which operate at the level of CSS values. It is expected that it will define "mixins" later, which are functions that operate at the style rule level.
Custom properties give authors a lot of power to define useful, sometimes complex values in one place, and then re-use them across their stylesheet. They can vary across the document, or based on Media Queries or other conditionals, making them very flexible and responsive.
However, their values are fixed at the point they’re defined, unable to be changed except by fully overriding their previous definition: a --shadow: 2px 2px var(--shadow-color) declaration takes its --shadow-color value from the element it’s declared on, and later changes to --shadow-color on descendant elements don’t alter the value of --shadow for them; they continue to use the shadow color defined where --shadow was defined. This is a common source of confusion for authors making heavy use of composite variables like this.
Custom functions allow authors the same power as custom properties, but parameterized: they have the same flexibility and conditionality as a custom property definition, but take values from other custom properties (or explicitly as arguments) at the point of use. For example, instead of a --shadow custom property, a --shadow() custom function could be defined instead, like:
@function --shadow ( --shadow-color <color> : inherit) { /* If --shadow-color argument isn't passed, or doesn't successfully parse as a <color>, try to use the --shadow-color *property* from the element instead */ /* var(--shadow-color) refers to the --shadow-color parameter, rather than a custom property, but can still use a fallback value as normal */ result:2 px 2 px var ( --shadow-color, black); } .foo{ --shadow-color : blue; box-shadow : --shadow (); /* produces a blue shadow */ /* or just */ box-shadow:--shadow ( blue); }
2. Defining Custom Functions
A custom function can be thought of as an advanced custom property, which instead of being substituted by a single fixed value, computes its substitution value based on function parameters and the value of custom properties at the point it’s invoked. Rather than the var() syntax that custom properties use for substitution, custom functions are invoked by <dashed-function> syntax, allowing additional values to be passed as arguments.
@function --negative ( --value) { result : calc ( -1 *var ( --value)); }
Then, that function can be referenced with --negative() in some declaration:
html{ --gap : 1 em ; padding : --negative ( var ( --gap)); /* or by passing the value explicitly, like: */ padding:--negative ( 1 em ); }
<dashed-function>s are arbitrary substitution functions, like var(). Their presence in a property’s value causes it to be assumed valid at parse time, and only evaluated and parsed at computed-value time, after arbitrary substitution has occurred.
2.1. The @function Rule
The @function rule defines a custom function, and consists of a name, a list of parameters, a function body, and optionally a return type described by a syntax definition.
Each function parameter consists of a name (<custom-property-name>); optionally a parameter type, described by a syntax definition; and optionally a default value.
<@function> = @function <function-token> <function-parameter>#? ) [ returns <css-type> ]? { <declaration-rule-list> } <function-parameter> = <custom-property-name> <css-type>? [ : <declaration-value> ]? <css-type> = <syntax-component> | <type()> <type()> = type( <syntax> )
2.1.1. The Function Preamble
The <function-token> production must start with two dashes (U+002D HYPHEN-MINUS), similar to <dashed-ident>, or else the definition is invalid.
The name of the resulting custom function is given by the name of the <function-token>, the optional function parameters are given by the <function-parameter> values (defaulting to an empty set), and the optional return type is given by the <css-type> following the returns keyword (defaulting to *).
@function --foo ( --a <length>) { /* ... */ } @function --foo ( --a <color>) { /* ... */ } @function --foo ( --a <length>+) { /* ... */ }
However, any <syntax> that requires a <syntax-combinator> needs to be wrapped in the type() function:
@function --foo ( --atype ( <number> | <percentage>)) { /* ... */ }
The name of a @function rule is a tree-scoped name. If more than one @function exists for a given name, then the rule in the stronger cascade layer wins, and rules defined later win within the same layer.
If the function parameters contain the same <custom-property-name> more than once, then the @function rule is invalid.
2.1.2. The Function Body
The body of a @function rule accepts conditional group rules, such as @media. Additionally, it accepts the following descriptors:
-
The result descriptor, which determines the result of evaluating the function. If no result descriptor exists, the function is valid, but always returns the guaranteed-invalid value.
-
Custom properties, providing local variables.
Unknown descriptors are invalid and ignored, but do not make the @function rule itself invalid.
2.2. The result Descriptor
Name: | result |
---|---|
For: | @function |
Value: | <declaration-value>? |
Initial: | n/a (see prose) |
The result descriptor defines the result of evaluating the custom function defined by its @function rule. Using var() functions, it can reference function parameters, local variables, as well as other custom functions via <dashed-function>s.
The result descriptor itself does not have a type, but its resolved value is type-checked during the substitution of a <dashed-function>.
2.3. Arguments & Local Variables
This section is non-normative.
Within a custom function’s function body, the var() function can access local variables (the custom properties defined in the function body), function parameters (the values passed to the function, or set to default values), and custom properties defined at the call site (an element, or another custom function).
In that list, earlier things "win" over later things of the same name—if you have a local variable named --foo, var(--foo) will be substituted by that local variable, not by an argument or a custom property defined outside. The other values can still be accessed, however: setting the --foo local variable to initial will resolve it to the --foo parameter, while inherit will resolve it to the --foo custom property from the call site.
@function --outer ( --outer-arg) { --outer-local : 2 ; result : --inner (); } @function --inner () returns <number>{ result : calc ( var ( --outer-arg) +var ( --outer-local)); } div{ z-index : --outer ( 1 ); /* 3 */ }
Similarly, custom properties are implicitly available:
@function --double-z () returns <number>{ result : calc ( var ( --z) *2 ); } div{ --z : 3 ; z-index : --double-z (); /* 6 */ }
But function parameters "shadow" custom properties, and local variables "shadow" both:
@function --add-a-b-c ( --b, --c) { --c : 300 ; result : calc ( var ( --a) +var ( --b) +var ( --c)); /* uses the --a from the call site's custom property, the --b from the function parameter, and the --c from the local variable */ } div{ --a : 1 ; --b : 2 ; --c : 3 ; z-index : --add-a-b-c ( 20 , 30 ); /* 321 */ }
3. Using Custom Functions
Similar to how the value of a custom property can be substituted into the value of another property with var(), the result of a custom function evaluation can be substituted into the value of a property with a <dashed-function>.
A <dashed-function> is a functional notation whose function name starts with two dashes (U+002D HYPHEN-MINUS). Its syntax is:
<dashed-function> = --*( <declaration-value># )
A <dashed-function> can only be used where var() is allowed.
If a property contains one or more <dashed-function>s, the entire property’s grammar must be assumed to be valid at parse time. At computed-value time, every <dashed-function> must be substituted before finally being checked against the property’s grammar.
Note: Within the body of a custom function, var() functions might resolve differently than on the element the <dashed-function> is used on. See § 3.1 Evaluating Custom Functions.
A <dashed-function> is evaluated in some context: either in a property value on an element (or in a descriptor that is eventually treated like a property on an element, such as in @keyframes), or in a descriptor in the function body of another custom function that is being applied to a "hypothetical" element. Either way, this provides a calling context, which contains the property or descriptor name containing the <dashed-function>, and the element (or "hypothetical" element) that property/descriptor is being applied to.
As calling contexts are nested by <dashed-function> evaluations inside of custom functions, a calling context’s root element is the real element at the root of the calling context stack.
-
Let function be the result of dereferencing the dashed function’s name as a tree-scoped reference. If no such name exists, return failure.
-
Substitute any arbitrary substitution functions within dashed function’s arguments, then parse it as <declaration-value># and let arguments be the result (a comma-separated list of CSS values).
-
If dashed function is being substituted into a property on an element, let calling context be a calling context with that element and that property
Otherwise, it’s being substituted into a descriptor on a "hypothetical element", while evaluating another custom function. Let calling context be a calling context with that "hypothetical element" and that descriptor.
-
Evaluate a custom function, using function, arguments, and calling context, and replace the <dashed-function> with the equivalent token sequence of the value resulting from the evaluation.
If substitute a dashed function fails, and the substitution is taking place on a property’s value, then the declaration containing the <dashed-function> becomes invalid at computed-value time.
{}
:
@function --max-plus-x ( --list, --x) { result : calc ( max ( var ( --list)) +var ( --x)); } div{ width : --max-plus-x ({ 1 px , 7 px , 2 px }, 3 px ); /* 10px */ }
3.1. Evaluating Custom Functions
Custom functions are evaluated by, essentially, pretending their function body is a style rule being applied to a hypothetical element, resolving styles as normal, and then returning the value of the result descriptor on that hypothetical element. The hypothetical element "inherits" the values of all custom properties as if it were a child of its calling context, with its function parameters overriding "inherited" custom properties of the same name.
-
If the number of items in arguments is greater than the number of function parameters in custom function, return the guaranteed-invalid value.
-
Let registrations be an initially empty set of custom property registrations.
-
For each function parameter of custom function, create a custom property registration with the parameter’s name, a syntax of the parameter type, an inherit flag of "true", and no initial value. Add the registration to registrations.
-
If custom function has a return type, create a custom property registration with the name "return" (violating the usual rules for what a registration’s name can be), a syntax of the return type, an inherit flag of "false", and no initial value. Add the registration to registrations.
-
Let argument rule be an initially empty style rule.
-
For each function parameter of custom function:
-
Let arg value be the value of the corresponding argument in arguments, or the guaranteed-invalid value if there is no corresponding argument.
-
Let default value be the parameter’s default value.
-
Add a custom property to argument rule with a name of the parameter’s name, and a value of first-valid(arg value, default value).
-
-
Resolve function styles using argument styles, registrations, and calling context. Let argument styles be the result.
-
Let body rule be the function body of custom function, as a style rule.
-
For each custom property registration of registrations, set its initial value to the corresponding value in argument styles, and prepend a custom property to body rule with the property name and value in argument styles.
-
Resolve function styles using body rule, registrations, and calling context. Let body styles be the result.
-
Return the value of the result property in body styles.
-
Create a "hypothetical element" el that acts as a child of calling context’s element. el is featureless, and only custom properties and the result descriptor apply to it.
-
Apply rule to el to the specified value stage, with the following changes:
-
Only the custom property registrations in registrations are visible; all other custom properties are treated as unregistered.
-
The inherited value of calling context’s property is the guaranteed-invalid value.
-
On custom properties, the CSS-wide keywords initial and inherit have their usual effect; all other CSS-wide keywords resolve to the guaranteed-invalid value.
Note: initial references the custom property registration created from the function parameters, letting you "reset" a property to the passed value. inherit inherits from the calling context’s element.\
On result, all CSS-wide keywords are left unresolved.
Note: result: inherit, for example, will cause the <dashed-function> to evaluate to the inherit keyword, similar to var(--unknown, inherit).
-
-
Determine the computed value of all custom properties and the result "property" on el, as defined in CSS Properties and Values API 1 § 2.4 Computed Value-Time Behavior, with changes from the previous step, and the following:
-
Aside from references to custom properties (which use the values on el as normal) and numbers/percentages (which are left unresolved in custom properties, as normal), all values which would normally refer to the element being styled instead refer to calling context’s root element.
Note: For example, attr() in a property, or @container queries in the rule.
-
-
Return el’s styles.
Note: Only custom properties and the result descriptor will be used from these styles.
3.2. Cycles
The result descriptor and local variables within a custom function may reference other custom functions or custom properties, and may therefore create cycles.
For each element, add a node for every specified custom function to the graph described in CSS Variables 1 § 2.3 Resolving Dependency Cycles; add a node for each local variable defined within each of those functions; then, for each custom function func, add edges as follows:
-
From func to any custom function referenced by a <dashed-function> within func’s body.
-
From func to any custom property or local variable referenced by a var() within func’s body.
-
To func from any custom property or local variable that references func using a <dashed-function>.
A <dashed-function> referencing a custom function which is part of a cycle makes the containing declaration invalid at computed-value time.
Note: Cycles are disallowed even through branches that are not taken during execution.
--foo ()
is in a cycle with itself,
even though the media query never evaluates to "true":
@function --foo ( --x) { @media ( unknown-feature) { result : --foo ( 42 ); } result:1 ; }
Similarly,
is in a cycle with itself,
even though the local variable --x
is never referenced:
@function --bar () { --x : --bar (); result : 1 ; }
--baz ()
is not in a cycle in the example below:
even though var ( --x)
and var ( --y)
appear in the function body,
they refer to a function parameter and local variable, respectively.
The custom properties --x
and --y
both reference --baz ()
, but that’s fine:
those custom properties are not referenced within --baz ()
.
@function --baz ( --x) { --y : 10 px ; result : calc ( var ( --x) +var ( --y)); } div{ --x : --baz ( 1 px ); --y : --baz ( 2 px ); width : var ( --x); /* 11px */ height:var ( --y); /* 12px */ }
4. Execution Model of Custom Functions
Like the rest of CSS, custom functions adhere to a declarative model.
The local variable descriptors and result descriptor can appear in any order, and may be provided multiple times. If this happens, then declarations appearing later win over earlier ones.
@function --mypi () { result : 3 ; result : 3.14 ; }
The value of the result descriptor of --mypi
is
.
@function --circle-area ( --r) { result : calc ( pi *var ( --r2)); --r2 : var ( --r) *var ( --r); }
Local variable descriptors may appear before or after they are referenced.
4.1. Conditional Rules
A conditional group rule that appears within a @function becomes a nested group rule, with the additional restriction that only descriptors allowed within @function are allowed within the nested group rule.
Conditional group rules within @function are processed as normal, acting as if the contents of the rule were present at the conditional group rule’s location when the condition is true, or acting as if nothing exists at that location otherwise.
@function --suitable-font-size () { result : 16 px ; @media ( width >1000 px ) { result : 20 px ; } }
The value of the result descriptor
is
if the media query’s condition is true,
and
otherwise.
@function --suitable-font-size () { @media ( width >1000 px ) { result : 20 px ; } result:16 px ; }
The value of the result descriptor
is always
in the above example.
@function --suitable-font-size () { --size : 16 px ; @media ( width >1000 px ) { --size : 20 px ; } result:var ( --size); }
5. CSSOM
The CSSFunctionRule
interface represents a @function rule.
[Exposed =Window ]interface :
CSSFunctionRule CSSGroupingRule { };
While declarations may be specified directly within a @function rule,
they are not represented as such in the CSSOM.
Instead, consecutive segments of declarations
appear as if wrapped in CSSFunctionDeclarations
rules.
Note: This also applies to the "leading" declarations in the @function rule, i.e those that do not follow another nested rule.
@function --bar () { --x : 42 ; result : var ( --y); @media ( width >1000 px ) { /* ... */ } --y:var ( --x); }
The above will appear in the CSSOM as:
@function --bar () { /* CSSFunctionDeclarations { */ --x:42 ; result : var ( --y); /* } */ @media ( width >1000 px ) { /* ... */ } /* CSSFunctionDeclarations { */ --y:var ( --x); /* } */ }
5.1. The CSSFunctionDeclarations
Interface
The CSSFunctionDeclarations
interface represents a run
of consecutive declarations within a @function rule.
[Exposed =Window ]interface :
CSSFunctionDescriptors CSSStyleDeclaration {attribute [LegacyNullToEmptyString ]CSSOMString ; }; [
result Exposed =Window ]interface :
CSSFunctionDeclarations CSSRule { [SameObject ,PutForwards =cssText ]readonly attribute CSSFunctionDescriptors style ; };
style
attribute
must return a CSSFunctionDescriptors
object for the rule,
with the following properties:
- computed flag
-
Unset
- readonly flag
-
Unset
- declarations
-
The declared declarations in the rule, in specified order. This includes any local variables.
- parent CSS rule
- owner node
-
Null
The CSSFunctionDeclarations
rule, like CSSNestedDeclarations
, serializes as if its declaration block had been serialized directly.
6. Privacy Considerations
The constructs defined by this specification are defined and used entirely within CSS; they expose no new information.
7. Security Considerations
No issues have been opened against this specification.