The CustomStateSet
interface of the Document Object Model stores a list of possible states for a custom element to be in, and allows states to be added and removed from the set.
Description
An HTML form element, such as a checkbox has different states, "checked" and "unchecked". Likewise, developers creating custom elements need to assign possible states to these elements. The CustomStateList
allows these states to be stored, and accessed from the custom element.
An instance of CustomStateList
is returned by ElementInternals.states
.
A CustomStateList
instance is a Set
-like object that can hold an ordered set of state values. Each value stored in a CustomStateList
is a <dashed-ident>
, in the format --mystate
.
Interaction with CSS
States are stored as a <dashed-ident>
as this format can then be accessed from CSS using the custom state pseudo-class. In the same way that you can use CSS to determine if a checkbox is checked using the :checked
pseudo-class, you can use a custom state pseudo-class to select a custom element that is in a certain state.
Instance properties
-
CustomStateSet.size
Experimental
-
Returns the number of values in the CustomStateSet
.
Instance methods
-
CustomStateSet.add()
Experimental
-
Adds a value to the set, first checking that the value is a <dashed-ident>
.
-
CustomStateSet.clear()
Experimental
-
Removes all elements from the CustomStateSet
object.
-
CustomStateSet.delete()
Experimental
-
Removes one value from the CustomStateSet
object.
-
CustomStateSet.entries()
Experimental
-
Returns a new iterator with the values for each element in the CustomStateSet
in insertion order.
-
CustomStateSet.forEach()
Experimental
-
Executes a provided function for each value in the CustomStateSet
object.
-
CustomStateSet.has()
Experimental
-
Returns a Boolean
asserting whether an element is present with the given value.
-
CustomStateSet.keys()
Experimental
-
An alias for CustomStateSet.values()
.
-
CustomStateSet.values()
Experimental
-
Returns a new iterator object that yields the values for each element in the CustomStateSet
object in insertion order.
Examples
The following function adds and removes the state --checked
to a CustomStateSet
, then prints to the console true
or false
as the custom checkbox is checked or unchecked.
The state of the element can be accessed from CSS using the custom state pseudo-class --checked
.
class MyCustomElement extends HTMLElement {
set checked(flag) {
if (flag) {
this._internals.states.add("--checked");
} else {
this._internals.states.delete("--checked");
}
console.log(this._internals.states.has("--checked"));
}
}
labeled-checkbox {
border: dashed red;
}
labeled-checkbox:--checked {
border: solid;
}
Specifications
Browser compatibility
|
Desktop |
Mobile |
|
Chrome |
Edge |
Firefox |
Internet Explorer |
Opera |
Safari |
WebView Android |
Chrome Android |
Firefox for Android |
Opera Android |
Safari on IOS |
Samsung Internet |
@@iterator |
90 |
90 |
No |
No |
76 |
No |
90 |
90 |
No |
64 |
No |
15.0 |
CustomStateSet |
90 |
90 |
No |
No |
76 |
No |
90 |
90 |
No |
64 |
No |
15.0 |
add |
90 |
90 |
No |
No |
76 |
No |
90 |
90 |
No |
64 |
No |
15.0 |
clear |
90 |
90 |
No |
No |
76 |
No |
90 |
90 |
No |
64 |
No |
15.0 |
delete |
90 |
90 |
No |
No |
76 |
No |
90 |
90 |
No |
64 |
No |
15.0 |
entries |
90 |
90 |
No |
No |
76 |
No |
90 |
90 |
No |
64 |
No |
15.0 |
forEach |
90 |
90 |
No |
No |
76 |
No |
90 |
90 |
No |
64 |
No |
15.0 |
has |
90 |
90 |
No |
No |
76 |
No |
90 |
90 |
No |
64 |
No |
15.0 |
keys |
90 |
90 |
No |
No |
76 |
No |
90 |
90 |
No |
64 |
No |
15.0 |
size |
90 |
90 |
No |
No |
76 |
No |
90 |
90 |
No |
64 |
No |
15.0 |
values |
90 |
90 |
No |
No |
76 |
No |
90 |
90 |
No |
64 |
No |
15.0 |