State Classes

State classes communicate temporary interface conditions — naming should stay predictable and understandable.

01 — Purpose

Temporary conditions, clear names

State classes communicate temporary interface conditions — state naming should remain predictable and understandable.

Open menus, active tabs, loading buttons, and error fields all share something: the DOM looks different for a moment. State classes make that visible to CSS — and to anyone reading the markup.

This site uses prefixes like is_open on the header nav and is_hidden when UI is removed from the page — not for screen-reader-only text (.vh handles that). See CSS naming conventions and the CSS standard for the wider naming system.

02 — Principles

Predictable state naming

State systems should improve clarity — not create ambiguity.

  • common patterns — is_active, is_open, is_hidden, has_error, is_loading
  • is_hidden removes UI from the page — not the same as .vh for visually hidden screen reader text
  • clear naming — state name describes condition, not visual treatment
  • restrained usage — only states that CSS or tests need to target
  • consistent patterns — one prefix convention across the codebase

03 — Practice

Good state class practice

Toggle classes from JavaScript; style them in CSS; keep ARIA in sync.

  • pair state with ARIA — aria-expanded when is_open toggles a menu
  • one source of truth — JS sets class; CSS reflects it; do not duplicate state in inline styles
  • document allowed states per component — modal: is_open; button: is_loading, is_disabled
  • use state for interaction feedback — not for permanent layout variants
  • test keyboard and screen reader behaviour when states change — see keyboard navigation

04 — Avoid

State ambiguity

Unclear or duplicated state logic breaks both CSS and assistive technology.

  • styling via JS-only assumptions — inline styles with no class hook for CSS
  • unclear naming — .on, .selected2, .activeTab mixed in one project
  • duplicated state logic — same open state tracked in three class names
  • state classes without JS cleanup — menu stays is_open after navigation
  • using state classes for theming — permanent dark mode is not is_dark on every element

05 — Close

State you can reason about

If you cannot grep for it, the convention has failed.

List component states in your CSS architecture doc. Review PRs for new state names — add to the system or reject the one-off.

See CSS naming conventions, CSS architecture, and ARIA usage.