Built-in elements have states you can style: :checked, :disabled, :open. Custom elements could not expose their own states to CSS, so authors fell back on attributes such as [loading] or classes that anyone could set from outside. The :state() pseudo-class fixes this, and it is about to reach Baseline Widely available. The modern.css Baseline tracker lists 17 November 2026 as the date. :state() became Baseline Newly available in May 2024, so after 30 months you can use it without worrying about browser support for most audiences. This tutorial builds a small web component that exposes real states, styles them from inside and outside, and shows the patterns to replace.
How custom states work
There are two halves:
- JavaScript: a custom element calls
this.attachInternals()and adds or removes strings frominternals.states, aCustomStateSet. - CSS:
:state(name)matches the element while that string is in its state set.
From the MDN reference:
:state(<custom-ident>) { /* ... */ }
The key benefit: only the element itself can change its states. Page code can’t fake :state(loading) by toggling an attribute, and the states don’t clutter the DOM.
Step 1: A component with real states
This <save-button> moves through idle, saving, saved and failed:
<save-button>Save changes</save-button>
<script type="module">
class SaveButton extends HTMLElement {
#internals;
constructor() {
super();
this.#internals = this.attachInternals();
const root = this.attachShadow({ mode: 'open' });
root.innerHTML = `
<style>
button { font: inherit; padding: .6em 1.2em; border-radius: .5em; }
:host(:state(saving)) button { opacity: .7; cursor: progress; }
:host(:state(saving)) button::after { content: " …"; }
</style>
<button part="button"><slot></slot></button>`;
root.querySelector('button').addEventListener('click', () => this.save());
}
#setState(name) {
for (const s of ['saving', 'saved', 'failed']) this.#internals.states.delete(s);
if (name) this.#internals.states.add(name);
}
async save() {
if (this.#internals.states.has('saving')) return;
this.#setState('saving');
try {
const res = await fetch('/api/save', { method: 'POST' });
this.#setState(res.ok ? 'saved' : 'failed');
} catch {
this.#setState('failed');
}
}
}
customElements.define('save-button', SaveButton);
</script>
Two things to notice. First, states are plain identifiers: use add('saving'), not add('--saving'). Second, states.has() gives the component a single source of truth for its own logic as well as for CSS.
Step 2: Style the states from the page
Users of the component can style it without knowing how it works inside:
save-button:state(saved) {
outline: 2px solid seagreen;
}
save-button:state(failed) {
outline: 2px solid crimson;
animation: shake .3s;
}
@keyframes shake {
25% { translate: -3px; }
75% { translate: 3px; }
}
This reads exactly like styling input:checked. The state is part of the component’s public styling API.
Step 3: Style from inside the shadow DOM
Inside the component’s own styles, wrap :state() in :host(), as in the <style> block above:
:host(:state(saving)) button { opacity: .7; }
MDN notes that :host(:state(x)) only matches within the shadow DOM of the current custom element. That makes it the right tool for default styles that ship with the component.
Step 4: Combine with ::part()
If a component exposes shadow parts, page authors can target a part while the host is in a state. MDN’s example uses a labeled-checkbox inside a question-box:
question-box::part(checkbox) {
color: red;
}
question-box::part(checkbox):state(checked) {
color: green;
outline: dashed 1px green;
}
In that example the part element is itself a custom element with a checked state. Pairing ::part() with :state() gives design systems a clean, documented styling surface: named parts plus named states, and no deep selectors.
Patterns to replace
| Old pattern | Problem | With :state() |
|---|---|---|
my-tabs[active-index="2"] reflected attributes |
Anyone can set them, and they clutter the HTML | Keep public attributes for inputs, use states for internal status |
.is-loading class added by the component |
Page code can remove or add it | :state(loading) can only be changed by the component |
Early :--loading syntax |
Non-standard and Chrome-only | :state(loading) |
A good rule: attributes are for configuration the page sets (disabled, variant="primary"), and custom states are for conditions the component reports (loading, invalid, expanded).
Accessibility: states are not ARIA
Custom states only affect styling. Screen readers don’t see them. If a state changes meaning, such as expanded/collapsed or busy, also set the right ARIA through ElementInternals. For example:
this.#internals.ariaBusy = name === 'saving' ? 'true' : 'false';
and announce results like “Saved” or “Save failed” with a live region if users need to hear them.
Testing and progressive enhancement
- Check state in tests by looking at the result, for example
el.matches(':state(saved)')from a test runner such as Playwright running in a real browser. - Keep your component’s default styles usable without any
:state()rules, so a very old browser shows a working, if plain, button. - If you must support older embedded webviews, use
@supports selector(:state(x))to add state styles only where they are understood:
@supports selector(:state(x)) {
save-button:state(failed) { outline: 2px solid crimson; }
}
Does this matter if you use React or another framework?
Yes, if you publish or consume web components. Design systems built with Lit, Stencil or plain custom elements can now tell framework apps “style us with :state(open)” instead of documenting fragile attribute selectors. The CSS works the same no matter which framework renders the element.
Takeaway
:state() gives custom elements the same kind of styling hooks as built-in elements: private to set, public to style, and kept out of the DOM. With Baseline Widely available arriving on 17 November 2026, it’s safe to use in production component libraries. Use internals.states for status, keep attributes for configuration, pair states with ARIA, and document your states next to your parts. Reference: MDN :state().
