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 */
}
Try the demo in Chrome

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.