This is an experimental technologyCheck 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.
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 tofalse
. 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/orinherits
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
Specification | Status | Comment |
CSS Properties and Values API Level 1The definition of 'The registerProperty() function' in that specification. | Working Draft | Initial definition. |
Browser compatibility
The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Update compatibility data on GitHub
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome
Full support 78 |
Edge
Full support 79 |
Firefox
No support No |
IE
No support No |
Opera
Full support 65 |
Safari
No support No |
WebView Android
Full support 78 |
Chrome Android
Full support 78 |
Firefox Android
No support No |
Opera Android
No support No |
Safari iOS
No support No |
Samsung Internet Android
Full support 12.0 |
Legend
- 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
CSS.registerProperty() by Mozilla Contributors is licensed under CC-BY-SA 2.5.