Chrome ships a state API for custom elements
Chrome 90 added support for custom state pseudo-classes (:--my-state), a feature that received little attention next to the release's declarative shadow DOM work. It extends the platform's pattern of "custom" hooks — like custom properties and custom elements — to element state.
The built-in baseline
Standard HTML elements already expose a range of states through widely supported pseudo-classes, defined in the CSS Selectors module and the "Pseudo-classes" section of the HTML Standard.
| User action | |
|---|---|
:hover |
the mouse cursor hovers over the element |
:active |
the element is being activated by the user |
:focus |
the element has the focus |
:focus-within |
the element has or contains the focus |
| Location | |
:visited |
the link has been visited by the user |
:target |
the element is targeted by the page URL’s fragment |
| Input | |
:disabled |
the form element is disabled |
:placeholder-shown |
the input element is showing placeholder text |
:checked |
the checkbox or radio button is selected |
:invalid |
the form element’s value is invalid |
:out-of-range |
the input element’s value is outside the specificed range |
:-webkit-autofill |
the input element has been autofilled by the browser |
| Other | |
:defined |
the custom element has been registered |
Why custom states
Custom elements have states of their own, and pages using them want to style those states. Exposing them through the class attribute on the host element is considered an anti-pattern. The new API instead lets an element publish internal states to the outer page via custom state pseudo-classes — here, a page using a <live-score> element targets its --loading state.
live-score {
/* default styles for this element */
}
live-score:--loading {
/* styles for when new content is loading */
}
Setting and styling state
The API lives in the custom element's class definition. The constructor creates an element internals object, and states are then set and unset on its internal states object.
class LabeledCheckbox extends HTMLElement {
constructor() {
super();
// 1. instantiate the element’s “internals”
this._internals = this.attachInternals();
// (other code)
}
// 2. toggle a custom state
set checked(flag) {
if (flag) {
this._internals.states.add("--checked");
} else {
this._internals.states.delete("--checked");
}
}
// (other code)
}
Because ElementInternals backs this, custom states are read-only from the outside: the page cannot modify a custom element's internal states.
The outer page then targets states by their names using matching custom pseudo-classes. In the example, the --checked state maps to :--checked.
labeled-checkbox {
/* styles for the default state */
}
labeled-checkbox:--checked {
/* styles for the --checked state */
}
Standards status
Browser vendors have debated the approach to exposing internal custom-element states for the past three years. Google's Custom State Pseudo Class specification remains an unofficial draft hosted by WICG. It underwent a design review at the W3C TAG and was handed over to the CSS Working Group. In the intent-to-ship discussion, Mounir Lamouri wrote:
It looks like this feature has good support. It sounds that it may be hard for web developers to benefit from it as long as it's not widely shipped, but hopefully Firefox and Safari will follow and implement it too. Someone has to implement it first, and given that there are no foreseeable backward incompatible changes, it sounds safe to go first.
Firefox and Safari implementations are still pending. Bugs exist — Mozilla #1588763 and WebKit #215911 — but have not received much attention yet.



