W3cubDocs

/Web APIs

CustomStateSet

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

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.

js

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"));
  }
}

css

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

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet