CSS Properties and Values API Level 1

Editor’s Draft,

This version:
https://drafts.css-houdini.org/css-properties-values-api-1/
Latest published version:
https://www.w3.org/TR/css-properties-values-api-1/
Previous Versions:
Feedback:
public-houdini@w3.org with subject line “[css-properties-values-api] … message topic …” (archives)
Issue Tracking:
Inline In Spec
GitHub Issues
Editors:
Tab Atkins-Bittner (Google)
Former Editors:

Abstract

This CSS module defines an API for registering new CSS properties. Properties registered using this API are provided with a parse syntax that defines a type, inheritance behaviour, and an initial value.

Status of this document

This is a public copy of the editors’ draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress.

GitHub Issues are preferred for discussion of this specification. When filing an issue, please put the text “css-properties-values-api” in the title, preferably like this: “[css-properties-values-api] …summary of comment…”. All issues and comments are archived.

This document was produced by the CSS Working Group.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2019 W3C Process Document.

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, via two methods:

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. Registered Custom Properties

A custom property can become a registered custom property, making it act more like a UA-defined property: giving it a syntax that’s checked by the UA, an initial value, and a specific inheritance behavior. This can be done by the @property rule, or the registerProperty() JS function.

A custom property is considered to be registered for a Document if there is a valid @property rule defined for its name in one of the document’s stylesheets, or its name is contained in the document’s [[registeredPropertySet]] slot (that is, registerProperty() was called to register it).

A registered custom property acts similarly to an unregistered custom property, except as defined below.

2.1. Determining the Registration

A registered custom property has a custom property registration that contains all the data necessary to treat it like a real property. It’s a struct consisting of:

If the Document’s [[registeredPropertySet]] slot contains a record with the custom property’s name, the registration is that record.

Otherwise, if the Document’s active stylesheets contain at least one valid @property rule representing a registration with the custom property’s name, the last such one in document order is the registration.

Otherwise there is no registration, and the custom property is not a registered custom property.

2.2. Parse-Time Behavior

Registered custom properties parse exactly like unregistered custom properties; almost anything is allowed. The registered syntax of the property is not checked at parse time.

Note: However, the syntax is checked at computed-value time, before substitution via var(). See § 2.4 Computed Value-Time Behavior.

Why aren’t custom properties syntax-checked?

When parsing a page’s CSS, UAs commonly make a number of optimizations to help with both speed and memory.

One of those optimizations is that they only store the properties that will actually have an effect; they throw away invalid properties, and if you write the same property multiple times in a single declaration block, all but the last valid one will be thrown away. (This is an important part of CSS’s error-recovery and forward-compatibility behavior.)

This works fine if the syntax of a property never changes over the lifetime of a page. If a custom property is registered, however, it can change its syntax, so that a property that was previously invalid suddenly becomes valid.

The only ways to handle this are to either store every declaration, even those that were initially invalid (increasing the memory cost of pages), or to re-parse the entire page’s CSS with the new syntax rules (increasing the processing cost of registering a custom property). Neither of these are very desirable.

Further, UA-defined properties have their syntax determined by the version of the UA the user is viewing the page with; this is out of the page author’s control, which is the entire reason for CSS’s error-recovery behavior and the practice of writing multiple declarations for varying levels of support. A custom property, on the other hand, has its syntax controlled by the page author, according to whatever stylesheet or script they’ve included in the page; there’s no unpredictability to be managed. Throwing away syntax-violating custom properties would thus only be, at best, a convenience for the page author, not a necessity like for UA-defined properties.

2.3. Specified Value-Time Behavior

Just like unregistered custom properties, all registered custom properties, regardless of registered syntax, accept the CSS-wide keywords, such as inherit or revert. Their behavior is defined in CSS Cascading 4 §7.3 Explicit Defaulting.

2.4. Computed Value-Time Behavior

The computed value of a registered custom property is determined by the syntax of its registration.

If the registration’s syntax is the universal syntax definition, the computed value is the same as for unregistered custom properties (either the specified value with variables substituted, or the guaranteed-invalid value).

Otherwise, attempt to parse the property’s value according to its registered syntax. If this fails, the computed value is the guaranteed-invalid value. If it succeeds, the computed value depends on the specifics of the syntax:

For "<length>", "<length-percentage>", "<angle>", "<time>", "<resolution>", "<integer>", "<number>", and "<percentage>" values:

For "<color>" values, the value is computed by resolving color values.

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

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

URL behavior examples
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.

On the other hand, if both --url-foo and --url-bar were unregistered, they would substitute their literal values (relative URLs) into the /index.html stylesheet, which would then resolve the URLs against /index.html instead.

For "<image>" values, the computed value is the computed <image>.

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

For values with multipliers, the computed value is a list of the computed values of the base type.

For syntaxes specified with the | combinator, the computed value is given by applying the computed-value rules for the first clause that matches the value.

2.5. Animation Behavior

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 property values interpolate by computed value, in accordance with the type that they parsed as.

Note: This implies that a list of values, such as <color>+ or <color>#, will interpolate as a simple list, matching up each component index-by-index, and failing if the number of components doesn’t match.

As an exception to the above rule, a value that parsed as a <transform-list>, a <transform-function>, or a <transform-function>+ instead interpolates as per the transform property.

Note: If, for whatever reason, a custom property is defined with a syntax of <transform-function>#, this will thus first interpolate as a simple list, and then each list item will interpolate as a transform value.

Note: Registering (or changing the registration) of a custom property can change its computed value, which can start or interrupt a CSS transition.

2.6. Conditional Rules

As stated in § 2.2 Parse-Time Behavior, both unregistered and registered custom properties accept (almost) all possible values at parse-time. Registered custom properties only apply their syntax at computed value time.

So, all custom properties, regardless of whether they’re registered or unregistered, will test as "true" in an @supports rule, so long as you don’t violate the (very liberal) generic syntax for custom properties.

For example, even if a custom property is registered with syntax: "<color>";, a rule like @supports (--foo: 1em) {...} will still evaluate as true and apply those styles, because the declaration does successfully parse as a valid property.

2.7. Substitution via var()

Like unregistered custom properties, the value of a registered custom property can be substituted into another value with the var() function. However, registered custom properties substitute as their computed value, rather than the original token sequence used to produce that value.

Any var() function that references a registered custom property must be replaced with an equivalent token sequence, which is equal to the token sequence that would have been produced by serializing the computed value, and tokenizing the resulting string.

Suppose that --x is registered with <length> syntax, and that '--y’is an unregistered custom property.
div {
  font-size: 10px;
  --x: 8em;
  --y: var(--x);
}

Because the computed value of --x (when serialized) is "80px", the computed value of --y is a <dimension-token> with a value of "80" and unit "px".

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

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

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. The @property Rule

The @property rule represents a custom property registration directly in a stylesheet without having to run any JS. Valid @property rules result in a registered custom property, as if registerProperty() had been called with equivalent parameters.

The syntax of @property is:

@property <custom-property-name> {
  <declaration-list>
}

A valid @property rule represents a custom property registration, with the property name being the serialization of the <custom-property-name> in the rule’s prelude.

@property rules require a syntax and inherits descriptor; if either are missing, the entire rule is invalid and must be ignored. The initial-value descriptor is optional only if the syntax is the universal syntax definition, otherwise the descriptor is required; if it’s missing, the entire rule is invalid and must be ignored.

Unknown descriptors are invalid and ignored, but do not invalidate the @property rule.

Note: As specified in § 2.1 Determining the Registration, if multiple valid @property rules are defined for the same <custom-property-name>, the last one in stylesheet order "wins". A custom property registration from CSS.registerProperty() further wins over any @property rules for the same <custom-property-name>.

A @property is invalid if it occurs in a stylesheet inside of a shadow tree, and must be ignored.

This will likely change in the future, as the behavior of concept-defining at-rules in shadow trees becomes more consistently defined. <https://github.com/w3c/css-houdini-drafts/issues/939>

3.1. The syntax Descriptor

Name: syntax
For: @property
Value: <string>
Initial: n/a (see prose)

Specifies the syntax of the custom property registration represented by the @property rule, controlling how the property’s value is parsed at computed value time.

The syntax descriptor is required for the @property rule to be valid; if it’s missing, the @property rule is invalid.

If the provided string is not a valid syntax string (if it returns failure when consume a syntax definition is called on it), the descriptor is invalid and must be ignored.

3.2. The inherits Descriptor

Name: inherits
For: @property
Value: true | false
Initial: n/a (see prose)

Specifies the inherit flag of the custom property registration represented by the @property rule, controlling whether or not the property inherits by default.

The inherits descriptor is required for the @property rule to be valid; if it’s missing, the @property rule is invalid.

3.3. The initial-value Descriptor

Name: initial-value
For: @property
Value: <declaration-value>
Initial: the guaranteed-invalid value (but see prose)

Specifies the initial value of the custom property registration represented by the @property rule, controlling the property’s initial value.

If the value of the syntax descriptor is the universal syntax definition, then the initial-value descriptor is optional. If omitted, the initial value of the property is the guaranteed-invalid value.

Otherwise, if the value of the syntax descriptor is not the universal syntax definition, the following conditions must be met for the the @property rule to be valid:

If the above conditions are not met, the @property rule is invalid.

4. Registering Custom Properties in JS

To register a custom property via JS, the CSS object is extended with a registerProperty() method:

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

partial namespace CSS {
  void registerProperty(PropertyDefinition definition);
};

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

4.1. The registerProperty() Function

The registerProperty(PropertyDefinition definition) method registers a custom property according to the configuration options provided in definition. When it is called, it executes the register a custom property algorithm, passing the options in its definition 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:
  1. Let property set be the value of the current global object’s associated Document’s [[registeredPropertySet]] slot.

  2. If name is not a custom property name string, throw a SyntaxError and exit this algorithm.

    If property set already contains an entry with name as its property name (compared codepoint-wise), throw an InvalidModificationError and exit this algorithm.

  3. Attempt to consume a syntax definition from syntax. If it returns failure, throw a SyntaxError. Otherwise, let syntax definition be the returned syntax definition.

  4. If syntax definition is the universal syntax definition, 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 definition is the universal syntax definition, 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 definition. 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.

  5. Set inherit flag to the value of inherits.

  6. Let registered property be a struct with a property name of name, a syntax of syntax definition, 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.4 Computed Value-Time Behavior.

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.

4.2. The PropertyDefinition Dictionary

A PropertyDefinition dictionary represents author-specified configuration options for a custom property. PropertyDefinition 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.

5. 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 definition, which is either:

  1. A list of syntax components, each of which accept the value types specified in § 5.1 Supported Names, or

  2. The universal syntax definition (*), 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.

5.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 definition, which is not a syntax component. Therefore, "*" may not be multiplied or combined with anything else.

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

5.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 definition with multiple syntax components.

When a syntax definition 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

5.4. Parsing The Syntax String

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

An object consisting of a list of syntax components.

universal syntax definition

A special syntax definition which accepts any valid token stream.

5.4.2. Consume a Syntax Definition

This section describes how to consume a syntax definition from a string string. It either produces a syntax definition with a list of syntax components, or the universal syntax definition.
  1. Strip leading and trailing ASCII whitespace from string.

  2. If string’s length is 0, return failure.

  3. If string’s length is 1, and the only code point in string is U+002A ASTERISK (*), return the universal syntax definition.

  4. Let stream be an input stream created from the code points of string, preprocessed as specified in [css-syntax-3]. Let definition be an initially empty list of syntax components.

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

    Consume as much whitespace as possible from stream.

    Consume the next input code point in stream:

    EOF

    return definition.

    U+007C VERTICAL LINE (|)

    Repeat step 5.

    Anything else:

    Return failure.

5.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 in 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 value. Otherwise return failure.

If component’s name does not parse as a <custom-ident>, 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.

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

6. CSSOM

The value specified for a registered custom property is not interpreted until computed-value time. This means that only APIs that retrieve computed values are affected. Other APIs must ignore the [[registeredPropertySet]] slot of the associated Document, and treat all custom properties as unregistered.

6.1. Extensions to the CSSRule Interface

The CSSRule interface is extended as follows:

partial interface CSSRule {
    const unsigned short PROPERTY_RULE = 18;
};

6.2. The CSSPropertyRule Interface

The CSSPropertyRule interface represents an @property rule.

[Exposed=Window]
interface CSSPropertyRule : CSSRule {
    readonly attribute CSSOMString name;
    readonly attribute CSSOMString syntax;
    readonly attribute boolean inherits;
    readonly attribute CSSOMString? initialValue;
};
name, of type CSSOMString, readonly
The custom property name associated with the @property rule.
syntax, of type CSSOMString, readonly
The syntax associated with the @property, exactly as specified.
inherits, of type boolean, readonly
The inherits descriptor associated with the @property rule.
initialValue, of type CSSOMString, readonly, nullable
The initial value associated with the @property rule, which may not be present.

6.3. CSSStyleValue Reification

To reify a registered custom property value given a property property and syntax definition syntax, run these steps:

For specified values, reify a list of component values from the value, and return the result.

For computed values:

  1. If the value is a <length>, <integer>, <number>, <angle>, <time>, <resolution>, <percentage> or <length-percentage>; reify a numeric value from the value and return the result.

  2. If the value is a <transform-function>, reify a <transform-function> from the value and return the result.

  3. If the value is a <transform-list>, reify a <transform-list> from the value and return the result.

  4. If the value is an <image>, reify a CSSImageValue from the value and return the result.

  5. If the value is an identifier, reify an identifier from the value and return the result.

  6. If syntax is the universal syntax definition, reify a list of component values from the value, and return the result.

  7. Otherwise, reify as a CSSStyleValue with the [[associatedProperty]] internal slot set to property, and return the result.

7. Examples

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

7.2. Example 2: Using @property to register a property

<script>
  CSS.paintWorklet.addModule('circle.js');
</script>
<style>
  @property --radius {
    syntax: "<length>";
    inherits: false;
    initial-value: 0px;
  }

  div {
    width: 100px;
    height: 100px;
    --radius: 10px;
    background: paint(circle);
    transition: --radius 1s;
  }

  div:hover {
    --radius: 50px;
  }
</style>
<div></div>
// circle.js
registerPaint('circle', class {
    static get inputProperties() { return ['--radius']; }
    paint(ctx, geom, properties) {
      let radius = properties.get('--radius').value;
      ctx.fillStyle = 'black';
      ctx.beginPath();
      ctx.arc(geom.width / 2, geom.height / 2, radius, 0, 2 * Math.PI);
      ctx.fill();
    }
});

8. Security Considerations

There are no known security issues introduced by these features.

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

This is an example of an informative example.

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

Note, this is an informative note.

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

Conformance to this specification is defined for three conformance classes:

style sheet
A CSS style sheet.
renderer
A UA that interprets the semantics of a style sheet and renders documents that use them.
authoring tool
A UA that writes a style sheet.

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

To avoid clashes with future stable CSS features, the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.

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 public-css-testsuite@w3.org mailing list.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSS-CASCADE-4]
Elika Etemad; Tab Atkins Jr.. CSS Cascading and Inheritance Level 4. 28 August 2018. CR. URL: https://www.w3.org/TR/css-cascade-4/
[CSS-COLOR-3]
Tantek Çelik; Chris Lilley; David Baron. CSS Color Module Level 3. 19 June 2018. REC. URL: https://www.w3.org/TR/css-color-3/
[CSS-COLOR-4]
Tab Atkins Jr.; Chris Lilley. CSS Color Module Level 4. 5 March 2019. WD. URL: https://www.w3.org/TR/css-color-4/
[CSS-CONDITIONAL-3]
CSS Conditional Rules Module Level 3 URL: https://www.w3.org/TR/css3-conditional/
[CSS-FONTS-3]
John Daggett; Myles Maxfield; Chris Lilley. CSS Fonts Module Level 3. 20 September 2018. REC. URL: https://www.w3.org/TR/css-fonts-3/
[CSS-IMAGES-4]
Tab Atkins Jr.; Elika Etemad; Lea Verou. CSS Image Values and Replaced Content Module Level 4. 13 April 2017. WD. URL: https://www.w3.org/TR/css-images-4/
[CSS-SYNTAX-3]
Tab Atkins Jr.; Simon Sapin. CSS Syntax Module Level 3. 16 July 2019. CR. URL: https://www.w3.org/TR/css-syntax-3/
[CSS-TRANSFORMS-1]
Simon Fraser; et al. CSS Transforms Module Level 1. 14 February 2019. CR. URL: https://www.w3.org/TR/css-transforms-1/
[CSS-TYPED-OM-1]
Shane Stephens; Tab Atkins Jr.; Naina Raisinghani. CSS Typed OM Level 1. 10 April 2018. WD. URL: https://www.w3.org/TR/css-typed-om-1/
[CSS-VALUES-4]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 4. 31 January 2019. WD. URL: https://www.w3.org/TR/css-values-4/
[CSS-VARIABLES]
Tab Atkins Jr.. CSS Custom Properties for Cascading Variables Module Level 1. 3 December 2015. CR. URL: https://www.w3.org/TR/css-variables-1/
[CSS2]
Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 7 June 2011. REC. URL: https://www.w3.org/TR/CSS2/
[CSS3-IMAGES]
Elika Etemad; Tab Atkins Jr.. CSS Image Values and Replaced Content Module Level 3. 17 April 2012. CR. URL: https://www.w3.org/TR/css3-images/
[CSS3-VALUES]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 3. 6 June 2019. CR. URL: https://www.w3.org/TR/css-values-3/
[CSSOM-1]
Simon Pieters; Glenn Adams. CSS Object Model (CSSOM). 17 March 2016. WD. URL: https://www.w3.org/TR/cssom-1/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WEB-ANIMATIONS-1]
Brian Birtles; et al. Web Animations. 11 October 2018. WD. URL: https://www.w3.org/TR/web-animations-1/
[WebIDL]
Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

Informative References

[CSS-LAYOUT-API-1]
Greg Whitworth; et al. CSS Layout API Level 1. 12 April 2018. WD. URL: https://www.w3.org/TR/css-layout-api-1/
[CSS-PAINT-API-1]
Ian Kilpatrick; Dean Jackson. CSS Painting API Level 1. 9 August 2018. CR. URL: https://www.w3.org/TR/css-paint-api-1/
[CSS3-ANIMATIONS]
Dean Jackson; et al. CSS Animations Level 1. 11 October 2018. WD. URL: https://www.w3.org/TR/css-animations-1/
[CSS3-TRANSITIONS]
David Baron; et al. CSS Transitions. 11 October 2018. WD. URL: https://www.w3.org/TR/css-transitions-1/

Property Index

No properties defined.

@property Descriptors

Name Value Initial
inherits true | false n/a (see prose)
initial-value <declaration-value> the guaranteed-invalid value (but see prose)
syntax <string> n/a (see prose)

IDL Index

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

partial namespace CSS {
  void registerProperty(PropertyDefinition definition);
};

partial interface CSSRule {
    const unsigned short PROPERTY_RULE = 18;
};

[Exposed=Window]
interface CSSPropertyRule : CSSRule {
    readonly attribute CSSOMString name;
    readonly attribute CSSOMString syntax;
    readonly attribute boolean inherits;
    readonly attribute CSSOMString? initialValue;
};

Issues Index

This will likely change in the future, as the behavior of concept-defining at-rules in shadow trees becomes more consistently defined. <https://github.com/w3c/css-houdini-drafts/issues/939>