Toggle switch

Problem Context

• The controlled item has clear on/off logic and the label can describe the same object in both states.
• Changing the setting is low risk, reversible, and expected to apply immediately.
• Users benefit from seeing the current state before deciding whether to change it.

Selection Rules

• Choose a toggle switch for a single setting with exactly two states that can be applied immediately.
• Keep the label stable, noun-based, and focused on the object being controlled rather than changing between action verbs.
• Show state text, effect text, or a status announcement when the effect is not obvious from the switch position alone.
• Use a checkbox group when the value is a submitted form answer or one of several independent choices users should review before commit.
• Use a radio group, segmented control, select, or another explicit choice pattern for three or more values.
• Use a button, menu item, or confirmation dialog for commands, destructive actions, and one-time operations.

Required States

• Off state.
• On state.
• Focused state.
• Pending or applying state when activation takes time.
• Disabled or unavailable state when a dependency, permission, or prerequisite blocks changes.
• Read-only state when the value can be reviewed but not changed.
• Failed application state when the service could not apply the requested setting.

Interaction Contract

• Activating the switch changes only the named setting between on and off.
• The state applies immediately unless a visible pending state explains the delay.
• The change is reversible without requiring additional confirmation.
• The accessible name remains stable while aria-checked or native checked state communicates the current value.
• Unavailable, disabled, read-only, pending, and failed states do not masquerade as successful on/off changes.

Implementation Checklist

• Use a native checkbox styled as a switch or a button with role switch and aria-checked.
• Associate a visible label and optional description with the switch.
• Keep the visible label stable across state changes.
• Expose on, off, focus, disabled, read-only, pending, and failed states through text, semantics, and visual styling.
• Use Space and, where supported, Enter to toggle custom switch implementations.
• Announce asynchronous changes through status text and reconcile the switch if the backend rejects the update.
• Keep the hit target large enough to activate through either the switch or its associated label.

Common Generated-UI Mistakes

• Using a switch to delete, publish, pay, submit, or trigger another one-time command.
• Hiding three or more options behind a binary-looking control.
• Changing the label after activation so users hear a different control name.
• Using a switch for legal consent, terms agreement, or a form answer that should be reviewed before submit.
• Showing an enabled-looking switch when dependencies, permissions, or service state prevent changes.

Critique Questions

• Can the setting honestly be described as on or off?
• Does the change apply immediately and remain reversible?
• Would users expect to review this value with other form answers before committing it?