Guide to the CSS.registerProperty() Method

The CSS.registerProperty() method is a JavaScript API provided by the CSS Houdini Properties and Values API that allows developers to explicitly register CSS custom properties with built-in type checking, default values, and inheritance rules. By defining custom properties with specific data types rather than generic strings, browsers can properly interpolate, animate, and validate CSS variables.

What is CSS.registerProperty()?

Standard CSS custom properties (variables) are treated by browsers as unparsed tokens or basic strings. Because the browser does not know whether a variable represents a color, length, or percentage, it cannot interpolate between values, making transitions and animations on standard custom properties impossible.

CSS.registerProperty() solves this by allowing developers to register a custom property directly within JavaScript, giving it structural metadata such as its expected syntax, whether it inherits down the DOM tree, and an initial fallback value.

Syntax and Parameters

The method is accessed via the global CSS object and accepts a single configuration object:

window.CSS.registerProperty({
  name: '--my-property',
  syntax: '<color>',
  inherits: false,
  initialValue: '#000000',
});

Parameters

  • name (string): The name of the custom property. It must begin with two dashes (e.g., --theme-color).
  • syntax (string): Specifies the data type for the property. Supported data types include <color>, <length>, <percentage>, <integer>, <number>, <image>, <url>, and <transform-list>, among others. You can also define alternatives using pipes (e.g., '<length> | <percentage>') or wildcards ('*').
  • inherits (boolean): Defines whether child elements inherit the value of this property from their parent elements.
  • initialValue (string): Sets the initial (default) value for the property. This is required unless the syntax is set to the wildcard *.

Practical Example: Animating CSS Gradients

One of the primary use cases for CSS.registerProperty() is enabling transitions on CSS gradients, which is not natively possible with standard custom properties.

// Register the custom property
if ('registerProperty' in CSS) {
  CSS.registerProperty({
    name: '--gradient-stop',
    syntax: '<color>',
    inherits: false,
    initialValue: 'blue',
  });
}

Once registered, the property can be transitioned smoothly via standard CSS:

.box {
  --gradient-stop: blue;
  background: linear-gradient(to right, red, var(--gradient-stop));
  transition: --gradient-stop 0.5s ease-in-out;
}

.box:hover {
  --gradient-stop: yellow;
}

Key Benefits

  • Smooth Transitions and Animations: The browser knows how to interpolate values across keyframes because the exact data type is defined.
  • Type Safety and Fallbacks: If an invalid value is provided in CSS, the browser discards it and falls back to the defined initialValue rather than breaking styles.
  • Performance: Registered properties are parsed directly by the browser's style engine rather than requiring runtime JavaScript recalculations.

Relationship to CSS @property

CSS.registerProperty() is the JavaScript equivalent of the CSS @property at-rule. While @property allows custom property registration directly inside a stylesheet, CSS.registerProperty() provides the same capabilities programmatically within JavaScript scripts and Houdini worklets.