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

• A JS API, the registerProperty() method

• A CSS at-rule, the @property rule

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:

• a property name (a custom property name string)

• a syntax (a syntax string)

• an inherit flag (a boolean)

• optionally, an initial value (a string which successfully parses according to the syntax)

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.

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 declaration is invalid at computed-value time and the computed value is determined accordingly. 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:

• If the specified value is a dimension literal (such as 50em or .2s), the computed value is the same value, but with the unit converted to the corresponding canonical unit for the type of value.

• If the specified value is any other numeric literal (such as 5 or 20%), the computed value is as specified. (In particular, percentages are never resolved against anything.)

• If the specified value is a function that evaluates to one of those types (such as a math function), the computed value is defined by that function.

For "<string>" values, the computed value is as specified.

For "<color>" values, the value is computed by resolving color values, per CSS Color 4 §  14. 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:

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

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

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

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

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.

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.

div {
  font-size: 10px;
  --x: 8em;
  --y: var(--x);
}

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:

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

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

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

2.8. Shadow DOM

Unlike many concepts in CSS (see CSS Scoping 1 § 2.5 Name-Defining Constructs and Inheritance), property registrations are not scoped to a tree scope. All registrations, whether they appear in the outermost document or within a shadow tree, interact in a single global registration map for the Document.

When custom properties are exposed as part of a Shadow DOM-using component’s public API, this global registration behavior works as intended. If the outer page is using a custom property of the same name for different purposes, that is already a conflict that needs to be resolved, and the registration behavior does not make it worse.

If a custom property is intended for private internal usage for a component, however, it is recommended that the property be given a likely-unique name, to minimize the possibility of a clash with any other context. This can be done, for example, by including the project name, or some short random string of text, in the name of the property.

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

3.1. The syntax Descriptor

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

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

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 @property rule to be valid:

• The initial-value descriptor must be present.

• The initial-value descriptor’s value must parse successfully according to the grammar specified by the syntax definition.

• The initial-value must be computationally independent.

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

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

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

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

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.

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.

"<string>"

Any valid <string> value

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

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

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

5.4.3. Consume a Syntax Component

5.4.4. Consume a Data Type Name

6. CSSOM

6.1. 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.2. CSSStyleValue Reification

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.

10. Changes

10.1. Changes since the Working Draft of 13 October 2020

/* to 20 March 2024 */

• Made "initial-value" have a <declaration-value>?, same as custom properties. (#9078)

• Allowed @Property in shadow trees. (#1085)

• Added section explaining why property registration is global, rather than shadow-scoped.

• Exported the terms "registered custom property" and "universal syntax definition", for use in other specifications. (#1020)

• Used the term "invalid at computed-value time" rather than "guaranteed-invalid value".