:state()

The :state() pseudo-class takes as its argument a custom identifier that represents the state of the custom element to match.

Elements can transition between states due to user interaction and other factors. For instance, an element can be in the "hover" state when a user hovers over the element, or a link can be in the "visited" state after a user clicks on it. Elements provided by browsers can be styled based on these states using CSS pseudo-classes such as :hover and :visited. Similarly, autonomous custom elements (custom elements that are not derived from built-in elements) can expose their states, allowing pages that use the elements to style them using the CSS :state() pseudo-class.

The states of a custom element are represented by string values. These values are added to or removed from a CustomStateSet object associated with the element. The CSS :state() pseudo-class matches an element when the identifier, passed as an argument, is present in the CustomStateSet of the element.

The :state() pseudo-class can also be used to match custom states within the implementation of a custom element. This is achieved by using :state() within the :host() pseudo-class function, which matches a state only within the shadow DOM of the current custom element.

Additionally, the ::part() pseudo-element followed by the :state() pseudo-class allows matching on the shadow parts of a custom element that are in a particular state. (Shadow parts are parts of a custom element's shadow tree that are explicitly exposed to a containing page for styling purposes.)

This CSS shows how to change the border of the autonomous custom element <labeled-checkbox> to red when it is in the "checked" state.

labeled-checkbox {
  border: dashed red;
}
labeled-checkbox:state(checked) {
  border: solid;
}

For a live example of this code in action, see the Matching the custom state of a custom checkbox element example on the CustomStateSet page.

This example shows how the :state() pseudo-class can be used within the :host() pseudo-class function to match custom states within the implementation of a custom element.

The following CSS injects a grey [x] before the element when it is in the "checked" state.

:host(:state(checked))::before {
  content: "[x]";
}

For a live example of this code in action, see the Matching the custom state of a custom checkbox element example on the CustomStateSet page.

This example shows how the :state() pseudo-class can be used to target the shadow parts of a custom element.

Shadow parts are defined and named using the part attribute. For example, consider a custom element named <question-box> that uses a <labeled-checkbox> custom element as a shadow part named checkbox:

shadowRoot.innerHTML = `<labeled-checkbox part='checkbox'>Yes</labeled-checkbox>`;

The CSS below shows how the ::part() pseudo-element can be used to match against the 'checkbox' shadow part. It then shows how the ::part() pseudo-element followed by the :state() pseudo-class can be used to match against the same part when it is in the checked state.

question-box::part(checkbox) {
  color: red;
}

question-box::part(checkbox):state(checked) {
  color: green;
}

For a live example of this code in action, see the Matching a custom state in a shadow part of a custom element example on the CustomStateSet page.

• CustomStateSet
• Pseudo-classes
• Learn: Pseudo-classes and pseudo-elements
• Custom states and custom state pseudo-class CSS selectors in Using custom elements