CSS.registerProperty()

The CSS.registerProperty() method registers custom properties, allowing for property type checking, default values, and properties that do or do not inherit their value.

Registering a custom property allows you to tell the browser how the custom property should behave; what are allowed types, whether the custom property inherits its value, and what the default value of the custom property is.

Syntax

CSS.registerProperty(PropertyDefinition);

Parameters

A PropertyDefinition dictionary object, which can contain the following members:

name

A DOMString indicating the name of the property being defined.

syntax Optional

A DOMString representing the expected syntax of the defined property. Defaults to "*".

inherits

A boolean value defining whether the defined property should be inherited (true), or not (false). Defaults to false.

initialValue Optional

A DOMString representing the initial value of the defined property.

Return value

undefined.

Exceptions

InvalidModificationError

The given name has already been registered.

SyntaxError

The given name isn't a valid custom property name (starts with two dashes, e.g. --foo).

TypeError

The required name and/or inherits dictionary members were not provided.

Examples

The following will register a custom property, --my-color, using registerProperty(), as a color, give it a default value, and have it not inherit its value:

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

In this example, the custom property --my-color has been registered using the syntax <color> . We can now use that property to transition a gradient on hover or focus. Notice that with the registered property the transition works, but that it doesn't with the unregistered property!

.registered {
  --my-color: #c0ffee;
  background-image: linear-gradient(to right, #fff, var(--my-color));
  transition: --my-color 1s ease-in-out;
}

.registered:hover,
.registered:focus {
  --my-color: #b4d455;
}

.unregistered {
  --unregistered: #c0ffee;
  background-image: linear-gradient(to right, #fff, var(--unregistered));
  transition: --unregistered 1s ease-in-out;
}

.unregistered:hover,
.unregistered:focus {
  --unregistered: #b4d455;
}
button {
  font-size: 3vw;
}

We can add these styles to some buttons:

<button class="registered">Background Registered</button>
<button class="unregistered">Background Not Registered</button>

Specifications

Browser compatibility

See also

• Using the CSS properties and values API
• CSS
• CSS.supports()
• CSS.escape()
• CSS factory functions