This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

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.




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

A DOMString indicating the name of the property being defined.
syntax Optional
A DOMString representing the expected syntax of the defined property. Defaults to "*".
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



The given name has already been registered.
The given name isn't a valid custom property name (starts with two dashes, e.g. --foo).
The required name and/or inherits dictionary members were not provided.


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:

  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:focus {
  --my-color: #b4d455;

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

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


Specification Status Comment
CSS Properties and Values API Level 1
The definition of 'The registerProperty() function' in that specification.
Working Draft Initial definition.

Browser compatibility

Update compatibility data on GitHub
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
Chrome Full support 78Edge Full support 79Firefox No support NoIE No support NoOpera Full support 65Safari No support NoWebView Android Full support 78Chrome Android Full support 78Firefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android Full support 12.0


Full support  
Full support
No support  
No support
Experimental. Expect behavior to change in the future.
Experimental. Expect behavior to change in the future.

See also