CSS: registerProperty() static method
MDN Web Docs · نسخهٔ df622a2a1c1e · CC BY-SA 2.5 و مجوز جداگانهٔ ناشر برای نمونهکد
{{APIRef("CSSOM")}}
The **CSS.registerProperty()** static 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 types are allowed, whether the custom property inherits its value, and what the default value of the custom property is.
Syntax
CSS.registerProperty(propertyDefinition)Parameters
propertyDefinition- : An object containing the following properties:
name- : A string representing the
{{cssxref("dashed-ident")}} name of the property being defined.
syntax{{optional_inline}}- : A string representing
the expected syntax of the defined property. Defaults to "*". See the {{cssxref("@property/syntax", "syntax")}}.
inherits- : A boolean value defining whether the defined property should be inherited
(true), or not (false). Defaults to false.
initialValue{{optional_inline}}- : A string representing
the initial value of the defined property.
Return value
undefined.
Exceptions
InvalidModificationError{{domxref("DOMException")}}- : The given
namehas already been registered. SyntaxError{{domxref("DOMException")}}- : The given
nameisn't a valid custom property name (starts with two
dashes, e.g., --foo).
- {{jsxref("TypeError")}}
- : The required
nameand/orinheritsdictionary 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 it doesn't work with the unregistered property!
.registered {
--my-color: #c0ffee;
background-image: linear-gradient(to right, white, 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, white, 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>{{EmbedLiveSample("Examples", 320, 320)}}
Specifications
{{Specifications}}
Browser compatibility
{{Compat}}
See also
- Using the CSS properties and values API
- {{DOMxRef("CSS")}}
- {{DOMxRef("CSS/supports_static", "CSS.supports()")}}
- {{DOMxRef("CSS/escape_static", "CSS.escape()")}}
- CSS factory functions
- CSS {{cssxref("@property")}}