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-1] and [css-layout-api-1], which allow custom properties to directly impact paint and layout behaviours respectively.

2. Registering custom properties

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

partial namespace CSS {
  void registerProperty(PropertyDescriptor descriptor);
};

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: 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()` function

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.

To register a custom property with name being a string, and optionally syntax being a string, inherits being a boolean, and initialValue being a string, execute these steps:

Let property set be the value of the current global object’s associated Document’s [[registeredPropertySet]] slot.
Attempt to parse name as a <custom-property-name>. If this fails, throw a SyntaxError and exit this algorithm.

Otherwise, let parsed name be the parsed value.

If property set already contains an entry with parsed name as its property name (compared codepoint-wise), throw an InvalidModificationError and exit this algorithm.
Attempt to consume a syntax descriptor from syntax. If it returns failure, throw a SyntaxError. Otherwise, let syntax descriptor be the returned syntax descriptor.
If syntax descriptor is the universal syntax descriptor, and initialValue is not present, let parsed initial value be empty. This must be treated identically to the "default" initial value of custom properties, as defined in [css-variables]. Skip to the next step of this algorithm.

Otherwise, if syntax descriptor is the universal syntax descriptor, parse initialValue as a <declaration-value>. If this fails, throw a SyntaxError and exit this algorithm. Otherwise, let parsed initial value be the parsed result. Skip to the next step of this algorithm.

Otherwise, if initialValue is not present, throw a SyntaxError and exit this algorithm.

Otherwise, parse initialValue according to syntax descriptor. If this fails, throw a SyntaxError and exit this algorithm.

Otherwise, let parsed initial value be the parsed result. If parsed initial value is not computationally independent, throw a SyntaxError and exit this algorithm.
Set inherit flag to the value of inherits.
Let registered property be a struct with a property name of parsed name, a syntax of syntax descriptor, an initial value of parsed initial value, and an inherit flag of inherit flag. Append registered property to property set.

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.

For example, 5px is computationally independent, as converting it into a computed value doesn’t change it at all. Similarly, 1in is computationally independent, as converting it into a computed value relies only on the "global knowledge" that 1in is 96px, which can’t be altered or adjusted by anything in CSS.

On the other hand, 3em is not computationally independent, because it relies on the value of font-size on the element (or the element’s parent). Neither is a value with a var() function, because it relies on the value of a custom property.

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.3 Calculation of Computed Values.

Note: A way to unregister properties may be added in the future.

Registering a custom property must not affect the cascade in any way. Regardless of what syntax is specified for a registered property, at parse time it is still parsed as normal for a custom property, accepting nearly anything. If the specified value for a registered custom property violates the registered syntax, however, the property becomes invalid at computed-value time (and thus resets to the registered initial value).

By default, all custom property declarations that can be parsed as a sequence of tokens are valid. Hence, the result of this stylesheet:

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

is to set the color property of elements of class "thing" to inherit. The second --my-color declaration overrides the first at parse time (both are valid), and the var() reference in the color property is found to be invalid at computed-value time (because url("not-a-color") is not a color). At this stage of the CSS pipeline (computation time), the only available fallback is the initial value of the property, which in the case of color is inherit. Although there was a valid usable value (green), this was removed during parsing because it was superseded by the URL.

If we call:

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

the parsing doesn’t significantly change, regardless of whether the registration occurs before or after the stylesheet above. The only difference is that it’s the --my-color property that becomes invalid at computed-value time instead and gets set to its initial value of black; then color is validly set to black, rather than being invalid at computed-value time and becoming inherit.

2.3. 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 <color> values, the value is computed as described in CSS Color 4 §4 Resolving Color values.

For <angle>, <time> and <resolution> values, the computed value is the value expressed in its canonical unit, with calc() expressions evaluated as described in CSS Values.

For <custom-ident>, ident, or "*" values, the computed value is as specified.

For <url> values, the computed value is one of the following:

if the URL is a relative URL, the computed value is the resolved absolute URL as described in [css3-values].
otherwise, the computed value is as specified.

For <image> values, the computed value is as specified, except that relative URLs that appear in the value are resolved to absolute URLs as described in [css3-values], and all lengths are resolved to their computed values.

For <integer>, <number> and <percentage> values, the computed value is one of the following:

if the specified value is a calc() expression, the computed value is the evaluated result of that expression.
otherwise, the computed value is as specified.

For <transform-function> values (including those 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.

2.4. Registered Properties and @supports

Unregistered custom properties are “always valid” when tested via @supports; a rule like `@supports (--foo: red) {...}` is always true so long as you don’t violate the (very liberal) syntax for custom properties.

Registering a custom property does not change this. Even if a custom property is, for example, registered with `syntax: " "`, a rule like `@supports (--foo: 1em) {...}` will still evaluate as true and apply those styles.

Note: This matches the parsing behavior of registered custom properties. A registered custom property specified as `" "` but written as `--foo: 1em;` will still be accepted as valid at parse-time, but be automatically invalid at computed-value time. As @supports tests parse behavior, it thus also accepts all values as valid regardless of the registered syntax.

2.5. Dependency cycles via relative units

Registered custom properties follow the same rules for dependency cycle resolution as unregistered custom properties, with the following additional constraints:

For any registered custom property with a <length> or <length-percentage> syntax component:

If the property contains any of the following units: em, ex, cap, ch, ic, lh; then add an edge between the property and the font-size of the current element.
If the property contains the lh unit, add an edge between the property and the line-height of the current element.
If the property contains any of the following units: rem, rlh; then add an edge between the property and the font-size' of the root element.
If the property contains the rlh unit, add an edge between the property and the line-height' of the root element.

For example, given this registration:

CSS.registerProperty({
  name: "--my-font-size",
  syntax: "<length>",
  initialValue: "0px",
  inherits: false
});

the following will produce a dependency cycle:

div {
  --my-font-size: 10em;
  font-size: var(--my-font-size);
}

and font-size will behave as if the value unset was specified.

3. Syntax Strings

A syntax string describes the value types accepted by a registered custom property. Syntax strings consists of syntax component names, that are optionally multiplied and combined.

A syntax string can be parsed into a syntax descriptor, which is either:

A list of syntax components, each of which accept the value types specified in §3.1 Supported names, or
The universal syntax descriptor (*), which accepts any valid token stream.

Note: Regardless of the syntax specified, all custom properties accept CSS-wide keywords, and process these values appropriately.

For example, the following are all valid syntax strings.

"<length>": accepts length values
"<length> | <percentage>": accepts lengths, percentages, percentage calc expressions, and length calc expressions, but not calc expressions containing a combination of length and percentage values.
"<length-percentage>": accepts all values that "<length> | <percentage>" would accept, as well as calc expressions containing a combination of both length and percentage values.
"big | bigger | BIGGER": accepts the ident big, or the ident bigger, or the ident BIGGER.
"<length>+": accepts a space-separated list of length values.
"*": accepts any valid token stream

Note: The internal grammar of syntax strings is a subset of the CSS Value Definition Syntax. Future levels of this specification are expected to expand the complexity of the allowed grammar, allowing custom properties that more closely resemble the full breadth of what CSS properties allow.

The remainder of this chapter describes the internal grammar of the syntax strings.

3.1. Supported names

This section defines the supported syntax component names, and the corresponding types accepted by the resulting syntax component.

"<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-function>"

Any valid <transform-function> value

"<custom-ident>"

Any valid <custom-ident> value

Any sequence which starts an identifier, can be consumed as a name, and 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.

"<transform-list>"

A list of valid <transform-function> values. Note that "<transform-list>" is a pre-multiplied data type name equivalent to "<transform-function>+"

Note: A syntax string of "*" will produce the universal syntax descriptor, which is not a syntax component. Therefore, "*" may not be multiplied or combined with anything else.

3.2. The '+' and '#' multipliers

Any syntax component name except pre-multiplied data type names may be immediately followed by a multiplier:

U+002B PLUS SIGN (+): Indicates a space-separated list.
U+0023 NUMBER SIGN (#): Indicates a comma-separated list.

"<length>+": accepts a space-separated list of length values
"<color>#": accepts a comma-separated list of color values

Note: The multiplier must appear immediately after the syntax component name being multiplied.

3.3. The '|' combinator

Syntax strings may use U+007C VERTICAL LINE (|) to provide multiple syntax component names. Such syntax strings will result in a syntax descriptor with multiple syntax components.

When a syntax descriptor with multiple syntax components is used to parse a CSS value, the syntax components are matched in the order specified.

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

"<length> | auto": accepts a length, or auto
"foo | <color># | <integer>": accepts foo, a comma-separated list of color values, or a single integer

3.4. Parsing the syntax string

3.4.1. Definitions

data type name: A sequence of code points consisting of a U+003C LESS-THAN SIGN (<), followed be zero or more name code points, and terminated by U+003E GREATER-THAN SIGN (>).
pre-multiplied data type name: A data type name that represents another syntax component with a multiplier already included.
syntax component: An object consisting of a syntax component name, and an optional multiplier.
syntax component name: A sequence of code points which is either a data type name, or a sequence that can produce a <custom-ident>.
syntax descriptor: An object consisting of a list of syntax components.
universal syntax descriptor: A special descriptor which accepts any valid token stream.

3.4.2. Consume a syntax descriptor

This section describes how to consume a syntax descriptor from a string string. It either produces a syntax descriptor with a list of syntax components, or the universal syntax descriptor.

Strip leading and trailing ASCII whitespace from string.
If string’s length is 0, return failure.
If string’s length is 1, and the only code point in string is U+002A ASTERISK (*), return the universal syntax descriptor.
Let stream be an input stream created from the code points of string, preprocessed as specified in [css-syntax-3]. Let descriptor be an initially empty list of syntax components.
Repeatedly consume the next input code point from stream:

whitespace

Do nothing.

EOF

If descriptor’s size is greater than zero, return descriptor; otherwise, return failure.

U+007C VERTICAL LINE (|)

Consume a syntax component from stream. If failure was returned, return failure; otherwise, append the returned value to descriptor.

anything else

Reconsume the current input code point in stream. Consume a syntax component from stream. If failure was returned, return failure; otherwise, append the returned value to descriptor.

3.4.3. Consume a syntax component

To consume a syntax component from a stream of code points stream:

Consume as much whitespace as possible from stream.

Let component be a new syntax component with its name and multiplier initially empty.

Consume the next input code point stream:

U+003C LESS-THAN SIGN (<): Consume a data type name from stream. If it returned a string, set component’s name to the returned value. Otherwise, return failure.
name-start code point
U+005C REVERSE SOLIDUS (\): If the stream starts with an identifier, reconsume the current input code point from stream then consume a name from stream, and set component’s name to the returned <ident-token>’s value. Otherwise return failure.
anything else: Return failure.

If component’s name is a pre-multiplied data type name, return component.

If the next input code point in stream is U+002B PLUS SIGN (+) or U+0023 NUMBER SIGN (#), consume the next input code point from stream, and set component’s multiplier to the current input code point.

Return component.

3.4.4. Consume a data type name

To consume a data type name from a stream of code points:

Note: This algorithm assumes that a U+003C LESS-THAN SIGN (<) code point has already been consumed from the stream.

Let name initially be a string containing a single U+003C LESS-THAN SIGN (<) code point.

Repeatedly consume the next input code point:

U+003E GREATER-THAN SIGN (>): Append the code point to name. If name is a supported syntax component name, return name. Otherwise return failure.
name code point: Append the code point to name.
anything else: Return failure.

4. Behavior of Custom Properties

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

4.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.3. Relative URLs

Relative URL values that appear in registered custom properties are resolved to full URLs as described in [css3-values].

Because URLs resolve against the base URL of the stylesheet they appear in, we can end up with multiple relative URLs that resolve against different base URLs, even though they appear in the same property.

For example, suppose --url-foo and --url-bar are registered custom properties with <url> syntax, and that we have a stylesheet at /style/foo/foo.css:

div {
  --url-foo: url("foo.png");
}

and another stylesheet at /style/bar/bar.css

div {
  --url-bar: url("bar.png");
}

and finally a document at /index.html:

<link href="/style/foo/foo.css" rel="stylesheet" type="text/css">
<link href="/style/bar/bar.css" rel="stylesheet" type="text/css">
<div style="background-image: var(--url-foo), var(---url-bar);">
</div>

Here, the var(--url-foo) reference would produce a URL that resolves against /style/foo, and the var(--url-bar) reference would produce a URL that resolves against /style/bar.

4.4. Fallbacks in var() references

References to registered custom properties using the var() function may provide a fallback. However, the fallback value must match the syntax descriptor of the custom property being referenced, otherwise the declaration is invalid at computed-value time.

Note: This applies regardless of whether or not the fallback is being used.

5. Examples

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

6. Security Considerations

There are no known security issues introduced by these features.

7. Privacy Considerations

There are no known privacy issues introduced by these features.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.

Conformance classes

A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

Partial implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

Implementations of Unstable and Proprietary Features

Non-experimental implementations

Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the [email protected] mailing list.