state()

Makes each matching element the owner of an independent state with an initial value.

Syntax

--name: state(<value> [, bind(…)] [, persist(…)]);

registry syntax: --name: state(initial [, bind(attribute)])

Parameters

valuetrue / false, <number>, <dimension>, keyword or color, <string>, attr() or pick()required

The initial value. It also works without JavaScript, as the native var() fallback. attr(name, fallback) reads the owner’s attribute once; since 0.9 a non-string fallback, as in state(attr(aria-expanded, false)), parses the attribute as that type.

bind()bind(value), bind(checked) or bind(<attribute>)optional

bind(value) and bind(checked) (0.9) bind the owner, a form control, in both directions: see bind() in state(). bind(<attribute>) (experimental, 0.5.2) reflects the state into the owner’s attribute (aria-expanded, aria-pressed, aria-selected, aria-current, aria-disabled, aria-hidden, aria-busy, aria-invalid, aria-checked, aria-valuenow, aria-label, aria-valuetext, disabled, hidden, required, tabindex, data-*), which initializes it once.

persist()persist("<key>" [, local | session])optional, experimental (0.9)

Keeps the state across reloads: see persist().

Return value

The current state. Booleans read as 1/0 through var(), strings as quoted CSS strings.

Example

.counter {  --count: state(0);}.counter .plus:on(click) {  --count: increment(1);}.counter .minus:on(click) {  --count: decrement(1);}.counter output::before {  counter-reset: n var(--count);  content: counter(n);}

Behavior

• Consumers use the nearest owner: the element itself, then its ancestors. Inner owners shadow outer ones.
• Created when the element starts matching a state() rule, disposed when it stops matching or is removed.
• Re-inserting an element starts over at the initial value. CSS recalculation never resets a state.
• Generated properties are registered with inherits: false, so nested owners stay isolated.
• The two modifiers, bind() and persist(), come in either order, each at most once: state("", persist("q"), bind(value)).

Supported contexts

• Only as the whole value of a custom property.

Limitations

• Memory only unless it has persist(): it resets on reload and when the stylesheet is edited.
• Existing states don’t pick up initial-value changes that come only from media queries.
• If a non-state declaration of the same property wins the cascade, var() shows that value, while conditions and actions keep using the state.

Examples

• Counter · API examples, runs the real runtime
• Conditional state · API examples, runs the real runtime

Related