CSS Properties and Values API Level 1

1. Introduction

CSS defines a comprehensive set of properties that can be manipulated in order to modify the layout, paint, or behaviour of a web document. However, web authors frequently wish to extend this set with additional properties.

[css-variables] provides primitive means for defining user-controlled properties, however these properties always take token lists as values, must always inherit, and can only impact document layout or paint by being re-incorporated into the value of other properties via a var() reference.

This specification extends [css-variables], allowing the registration of properties that have a value type, an initial value, and a defined inheritance behaviour.

This specification is complementary to [css-paint-api] and [css-layout-api], which allow custom properties to directly impact paint and layout behaviours respectively.

2. Registering custom properties

dictionary PropertyDescriptor {
    required DOMString name;
             DOMString syntax       = "*";
             boolean   inherits     = false;
             DOMString initialValue;
};


partial interface CSS {
    static void registerProperty(PropertyDescriptor descriptor);
    static void unregisterProperty(DOMString name);
};

Additional, the Document object gains a new [[registeredPropertySet]] private slot, which is a set of records that describe registered custom properties.

2.1. The PropertyDescriptor dictionary

A PropertyDescriptor dictionary represents author-specified configuration options for a custom property. PropertyDescriptor dictionaries contain the following members:

name, of type DOMString

The name of the custom property being defined.

syntax, of type DOMString, defaulting to "*"

A string representing how this custom property is parsed.

inherits, of type boolean, defaulting to false

True if this custom property should inherit down the DOM tree; False otherwise.

initialValue, of type DOMString

The initial value of this custom property.

2.2. The registerProperty() and unregisterProperty() functions

The registerProperty(PropertyDescriptor descriptor) method registers a custom property according to the configuration options provided in descriptor. When it is called, it executes the register a custom property algorithm, passing the options in its descriptor argument as arguments of the same names.

A property value is computationally independent if it can be converted into a computed value using only the value of the property on the element, and "global" information that cannot be changed by CSS.

When a custom property is registered with a given type, the process via which specified values for that property are turned into computed values is defined fully by the type selected, as described in §2.4 Calculation of Computed Values.

Properties can be unregistered using unregisterProperty(DOMString name). When it is called, it executes the unregister a custom property algorithm, with a name set to its sole argument.

When the current global object’s associated Document’s [[registeredPropertySet]] changes, previously syntactically invalid property values can become valid and vice versa. This can change the set of declared values which requires the cascade to be recomputed.

.thing {
    --my-color: green;
    --my-color: url("not-a-color");
    color: var(--my-color);
}

CSS.registerProperty({
    name: "--my-color",
    syntax: "<color>",
    initialValue: "black"
});

2.3. Supported syntax strings

The following syntax strings are supported:

"<length>"

Any valid <length> value

"<number>"

<number> values

"<percentage>"

Any valid <percentage> value

"<length-percentage>"

Any valid <length> or <percentage> value, any valid <calc()> expression combining <length> and <percentage> components.

"<color>"

Any valid <color> value

"<image>"

Any valid <image> value

"<url>"

Any valid <url> value

"<integer>"

Any valid <integer> value

"<angle>"

Any valid <angle> value

"<time>"

Any valid <time> value

"<resolution>"

Any valid <resolution> value

"<transform-list>"

A list of valid <transform-function> values

"<custom-ident>"

Any valid <custom-ident> value

Any sequence consisting of a name-start code point, followed by zero or more name code points, which matches the <custom-ident> production

That identifier

Note: <custom-ident>s are compared codepoint-wise with each other; this is different than the normal behavior of UA-defined CSS which limits itself to ASCII and is ASCII case-insensitive. So, specifying an ident like Red means that the precise value Red is accepted; red, RED, and any other casing variants are not matched by this. It is recommended that idents be restricted to ASCII and written in lower-case, to match CSS conventions.

One of the preceding strings, followed by '+'

A space-separated list of one or more repetitions of the type specified by the string. Note: Since <transform-list> is already a space separated list, <transform-list>+ is invalid.

Any combination of the preceding, separated by '|'

Any value that matches one of the items in the combination, matched in specified order.

Note: That is, given the syntax string "red | <color>", matching the value red against it will parse as an identifier, while matching the value blue will parse as a <color>.

"*"

Any valid token stream

Note: [css3-values] maintains a distinction between properties that accept only a length, and properties that accept both a length and a percentage, however the distinction doesn’t currently cleanly line up with the productions. Accordingly, this specification introduces the length-percentage production for the purpose of cleanly specifying this distinction.

Regardless of the syntax specified, all custom properties will accept CSS-wide keywords as well as revert, and process these values appropriately.

Note: This does not apply to the initialValue member of the PropertyDescriptor dictionary.

2.4. Calculation of Computed Values

The syntax of a custom property fully determines how computed values are generated from specified values for that property.

The CSS-wide keywords and revert generate computed values as described in [css3-values] and [css-cascade-4] respectively. Otherwise:

For <length> values, the computed value is the absolute length expressed in pixels.

For <length-percentage> values, the computed value is one of the following:

• if the specified value contains only length units, the computed value is the absolute length expressed in pixels.

• if the specified value contains only percentages, the computed value is a simple percentage.

• otherwise, the computed value is a calc expression containing an absolute length expressed in pixels, and a percentage value.

For <custom-ident>, ident, <color>, <image>, <url>, <integer>, <angle>, <time>, <resolution> or "*" values, the computed value is as specified.

For <number> and <percentage> values which are not calc expressions, the computed value is as specified. Calc expressions that are <number> and <percentage> values get reduced during computation to simple numbers and percentages respectively.

For <transform-function> values contained in <transform-list> values, the computed value is as specified but with all lengths resolved to their computed values.

For values specified by a syntax string that include "|" clauses, the computed value is given by applying the calculation rules for the first clause that matches to the specified value.

For list values, the computed value is a list of the computed values of the primitives in the list.

3. Behavior of Custom Properties

3.1. Animation Behavior of Custom Properties

Note: As defined by [css3-animations] and [css3-transitions], it is possible to specify animations and transitions that reference custom properties.

When referenced by animations and transitions, custom properties interpolate in a manner defined by their types. If their type is defined as a list with "+", it’s interpolated as a simple list [css3-transitions].

If the start and end of an interpolation have matching types, then they will interpolate as specified in [css3-animations]. Otherwise, the interpolation falls back to the default 50% flip described in [css3-animations].

Intermediate interpolated results of animations on custom properties must be able to generate a token stream representing their value. We should ensure that this is standard across implementations to avoid interop issues.

3.2. Conditional Rules

@supports rules and the supports(conditionText) method behave as specified in [css-variables].

Note: In other words, for the purpose of determining whether a value is supported by a given custom property, the type registered for the custom property is ignored and any value consisting of at least one token is considered valid.

should @supports pay attention to type when considering custom properties? <https://github.com/w3c/css-houdini-drafts/issues/118>

4. Examples

4.1. Example 1: Using custom properties to add animation behavior

<script>
CSS.registerProperty({
    name: "--stop-color",
    syntax: "<color>",
    inherits: false,
    initialValue: "rgba(0,0,0,0)"
});
</script>


<style>


.button {
    --stop-color: red;
    background: linear-gradient(var(--stop-color), black);
    transition: --stop-color 1s;
}


.button:hover {
    --stop-color: green;
}


</style>

5. Security Considerations

There are no known security issues introduced by these features.

6. Privacy Considerations

There are no known privacy issues introduced by these features.