UX Patterns Guide
UI + UX Selection And Choice standard

Toggle switch

Present one stable label with a binary switch state, immediate reversible application, visible state text when helpful, and explicit pending, unavailable, disabled, or read-only states when the setting cannot simply flip.

Open in lab Compare alternatives
Decision first

Choose this pattern when the problem matches

Use when

  • A single setting, feature, preference, or hardware-like control has two clear states.
  • The setting can take effect immediately or can clearly show a short pending state.
  • The change is reversible and low risk.

Avoid when

  • The action is destructive, one-time, legal, financial, or needs confirmation.
  • There are more than two possible values.
  • The value is part of a submitted form answer that should wait for Save or Continue.
  • The label cannot explain both states without changing after activation.

Problem it prevents

Users need to turn one setting, feature, preference, or hardware-like option on or off and understand whether the change has taken effect.

Test the behavior

Open the interactive example when you need it

The full lab is intentionally loaded on request. That keeps this reading page fast while preserving the strong and weak states, keyboard checks, and failure scenarios.

In the lab you can
  • switch between strong UI, weak UI, strong UX, and weak UX;
  • trigger required, empty, loading, error, and recovery states;
  • inspect keyboard and accessibility expectations beside the demo.
Launch Toggle switch in the lab
Pattern anatomy

What a strong implementation has to make clear

User need

The controlled item has clear on/off logic and the label can describe the same object in both states.

Pattern promise

Present one stable label with a binary switch state, immediate reversible application, visible state text when helpful, and explicit pending, unavailable, disabled, or read-only states when the setting cannot simply flip.

Required state

Off state.

Recovery path

The switch looks on while the service is still offline.

Access contract

Use role switch with aria-checked or a native checkbox implementation that exposes the checked state.

Quality bar

The difference between expert and weak execution

Strong implementation

Specific, visible, recoverable

  • A notifications switch with a stable Notifications label, On or Off state text, large hit target, visible focus, and immediate applied effect.
  • A disabled switch paired with dependency text that explains why the setting is unavailable.
  • Turning the switch on immediately enables the setting and announces the applied effect.
  • A delayed backend update shows pending state, then either confirms the setting or explains the failure and reconciles the switch.
Weak implementation

Vague, hidden, hard to recover from

  • A red switch labelled Delete account that behaves like an instant destructive command.
  • A switch whose label changes from Enable emails to Disable emails after activation.
  • A switch appears to change but requires a hidden Save button before anything happens.
  • Off, weekly, and daily notification choices are forced into one binary switch.
UI guidance
  • Render one switch with a stable visible label, clear on/off state, visible focus, accessible state, and optional state text when the effect is not obvious.
  • Include pending, failed, unavailable, disabled, and read-only styling so asynchronous or blocked settings are not confused with successful state changes.
UX guidance
  • Let users change one reversible setting immediately and understand the applied effect.
  • Avoid using switches for commands, destructive work, multi-value choices, consent, or staged form answers that should wait for a Save or Continue action.
Implementation contract

What the implementation must handle

States

  • Off state.
  • On state.
  • Focused state.
  • Pending or applying state when activation takes time.

Interaction

  • 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.

Accessibility

  • Use role switch with aria-checked or a native checkbox implementation that exposes the checked state.
  • Provide a stable accessible name and associate any explanatory text through description semantics.
  • Do not rely on color, position, or animation alone to communicate on, off, pending, disabled, read-only, or failed state.
  • Keep disabled and read-only states understandable to assistive technology users.

Review

  • 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?
Evidence trail

Source-backed claims behind this guidance

WAI-ARIA APG Switch Pattern

W3C Web Accessibility Initiative - checked

APG switch guidance defines binary on/off semantics, stable labels, accessible names, aria-checked state, and keyboard toggling expectations.

Carbon Design System Toggle

IBM Carbon Design System - checked

Carbon toggle guidance supports immediate reversible binary setting changes and documents on, off, focus, disabled, read-only, skeleton, label, state text, and click target behavior.

GNOME switch guidance limits switches to clear on/off features, settings, or hardware and documents delayed effect and unavailable-state handling.

Full agent/debug reference

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?
Accessibility
  • Use role switch with aria-checked or a native checkbox implementation that exposes the checked state.
  • Provide a stable accessible name and associate any explanatory text through description semantics.
  • Do not rely on color, position, or animation alone to communicate on, off, pending, disabled, read-only, or failed state.
  • Keep disabled and read-only states understandable to assistive technology users.
Keyboard Behavior
  • Tab moves focus to the switch when it is interactive.
  • Space toggles the focused switch.
  • Enter may toggle custom switch implementations when the platform convention supports it.
  • Tab moves away from the switch without losing the changed state.
Variants
  • Settings switch
  • Inline table-row switch
  • Feature flag switch
  • Hardware control switch
  • Read-only switch state

Verification

Source trail checked:

Saved items