Migrating from Dashed-Ident Custom States: From :–loading to :state(loading)

CustomStateSet shipped twice. The first version, in Chromium 90, required every state name to be a dashed ident — a string beginning with two hyphens — and matched it with a pseudo-class of the same shape: states.add('--loading') paired with :--loading. The second, standardised version uses a plain identifier and an explicit functional pseudo-class: states.add('loading') paired with :state(loading).

Both shapes were live in shipping Chromium for four years, which means real component libraries, real design-system stylesheets, and real application CSS were written against the old one. A migration is therefore not a find-and-replace on one repository; it is a coordinated change across a component’s internals, its own stylesheet, and every consumer stylesheet the team does not control. This deep dive belongs to Custom States & State-Driven Styling inside Styling, Theming & CSS Encapsulation.

Problem Statement: The Component That Works in One Browser

class SyncBadge extends HTMLElement {
  #internals;

  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.attachShadow({ mode: 'open' }).innerHTML = `
      <style>
        :host { display: inline-block; padding: 0.2rem 0.6rem; border-radius: 999px; }
        /* Legacy syntax: works only on Chromium 90–124. */
        :host(:--syncing) { background: #fff3cd; }
        :host(:--offline) { background: #f8d7da; }
      </style>
      <slot></slot>`;
  }

  connectedCallback() {
    // Legacy naming: the leading dashes are part of the state name.
    this.#internals.states.add('--syncing');
  }
}
customElements.define('sync-badge', SyncBadge);

On Chromium 124 this renders correctly. On Chromium 125 and later the selector :--syncing no longer parses as a custom state, so the rule is dropped and the badge loses its colour. On Firefox and Safari the component never worked at all — those engines only ever implemented the standard form, so both the add('--syncing') call and the selector were inert. The result is a component that looks fine in the browser it was developed in and unstyled everywhere else, with no error in any console.

Root-Cause Analysis

The change was deliberate and was made for a syntactic collision. A dashed ident is already meaningful in CSS: --foo is the syntax for a custom property, and CSS Values Level 5 reserves the -- prefix for author-defined names generally. Using the same prefix for a pseudo-class created a parsing ambiguity with proposed features — notably custom selectors — and gave authors no way to tell at a glance whether :--loading was a state, a future custom selector, or a typo.

The CSS Working Group resolved it by moving custom states into an explicit functional form, :state(), which is unambiguous, greppable, and consistent with :is(), :where(), :has(), and :not(). The state name then became an ordinary identifier, so the leading dashes disappeared from both sides.

Three consequences shape the migration.

The two forms are disjoint, not overlapping. No engine version accepts both. Chromium 125 removed the old parsing when it added the new; Firefox and Safari only ever had the new. There is therefore no single string that works everywhere, and the transition requires shipping both.

State names and selectors must move together. states.add('--syncing') makes :state(--syncing) match, not :state(syncing) — because the name really is the string you added, dashes included. A team that updates only the stylesheet gets no match; a team that updates only the JavaScript gets no match. This is the single most common way the migration goes wrong.

Consumer stylesheets are outside your repository. A design system that documented my-el:--loading as a theming hook has consumers with that selector in their own CSS. Removing the old state name silently unstyles their pages. This is an API break and needs a deprecation window, not a patch release.

Production-Safe Migration

The transitional component sets both names and ships both selectors. Because no engine understands both, the duplication costs one extra string per state and one extra rule per declaration block, and the invalid rule is simply dropped by whichever engine does not recognise it.

/** Adds or removes a state under BOTH the standard and legacy names. */
const setState = (states, name, on) => {
  const legacy = `--${name}`;
  if (on) {
    states.add(name);
    // Older Chromium rejects nothing here; newer engines just carry a second string.
    states.add(legacy);
  } else {
    states.delete(name);
    states.delete(legacy);
  }
};

class SyncBadge extends HTMLElement {
  #internals;

  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.attachShadow({ mode: 'open' }).innerHTML = `
      <style>
        :host { display: inline-block; padding: 0.2rem 0.6rem; border-radius: 999px; }

        /* Standard form — Chromium 125+, Firefox 126+, Safari 17.4+. */
        :host(:state(syncing)) { background: #fff3cd; color: #664d03; }
        :host(:state(offline)) { background: #f8d7da; color: #842029; }

        /* Legacy form — Chromium 90–124. MUST be a separate rule: an unknown
           selector in a comma-separated list invalidates the whole list. */
        :host(:--syncing) { background: #fff3cd; color: #664d03; }
        :host(:--offline) { background: #f8d7da; color: #842029; }
      </style>
      <slot></slot>`;
  }

  set syncing(on) { setState(this.#internals.states, 'syncing', Boolean(on)); }
  get syncing() { return this.#internals.states.has('syncing'); }

  set offline(on) { setState(this.#internals.states, 'offline', Boolean(on)); }
  get offline() { return this.#internals.states.has('offline'); }
}
customElements.define('sync-badge', SyncBadge);

The comment on the legacy rules is the part most migrations get wrong. CSS error handling discards an entire selector list containing an unparseable selector, so writing :host(:state(syncing)), :host(:--syncing) { … } produces no styling on either engine — the modern one chokes on :--syncing, the legacy one chokes on :state(). They must be separate rules with duplicated declarations, or the duplication must be generated by a build step.

For consumers, publish the new selector in the documentation immediately, keep the legacy state name for one major version, and emit a development-mode warning when a legacy name is observed in use. When the deprecation window closes, delete the legacy branch of setState and the legacy rules together — in the same commit, so the two halves cannot drift.

Verification

const badge = document.querySelector('sync-badge');
badge.syncing = true;

// Both names are present during the transition window.
console.assert(badge.matches(':state(syncing)'), 'standard state set');

// Feature-detect which syntax this engine understands.
const supportsStandard = CSS.supports('selector(:state(x))');
const supportsLegacy = CSS.supports('selector(:--x)');
console.log({ supportsStandard, supportsLegacy });
console.assert(supportsStandard !== supportsLegacy, 'exactly one syntax is live per engine');

// The styling consequence, which is what actually matters.
const bg = getComputedStyle(badge).backgroundColor;
console.assert(bg !== 'rgba(0, 0, 0, 0)', 'a state rule applied in this engine');

// And it clears cleanly on both names.
badge.syncing = false;
console.assert(!badge.matches(':state(syncing)'), 'standard name cleared');
console.assert(getComputedStyle(badge).backgroundColor !== bg, 'styling reverted');

CSS.supports('selector(...)') is the reliable detector and is worth keeping in the codebase past the migration, because it turns “which syntax does this engine want” from tribal knowledge into a runtime fact. In DevTools, the Styles pane greys out rules whose selector did not parse, which makes the legacy block visibly inert on a modern engine — a good confirmation that the duplication is doing what you think.

When to Use vs When to Avoid

The fourth row deserves a note. If the stylesheet is authored in a preprocessor or generated from tokens, a small mixin that emits both rules from one source removes the risk of the two copies diverging. Hand-maintained duplication is workable for three or four states and error-prone beyond that.

Frequently Asked Questions

Related

• Custom States & State-Driven Styling — the parent topic on CustomStateSet.
• Styling, Theming & CSS Encapsulation — the section this deep dive belongs to.
• Styling Custom States with the :state() Selector — the selector forms you are migrating to.
• Exposing Loading States to Consumer CSS — why the state vocabulary is public API.
• Polyfilling Custom Elements in Legacy Browsers — the broader support-floor strategy.