behavior variant · Choice and binary state controls

Toggle Button

A button that stays pressed or not pressed to represent a persistent mode or state while retaining button semantics.

reviewpublishedV1 field note

Decisive boundary

If the control represents an on or off setting rather than a button-owned mode, use a Switch; if it selects form values, use Checkbox or Radio Group semantics.

Definition and intent

What is a Toggle Button UI pattern?

Use the behavior, not the silhouette

A button that stays pressed or not pressed to represent a persistent mode or state while retaining button semantics. The term is used here as a behavior variant that normally modifies another control rather than defining a complete component by itself. That distinction prevents a visual resemblance from silently deciding focus, keyboard, modality, or dismissal behavior.

Keep a reversible button-controlled mode visibly and programmatically pressed until it is turned off. A good implementation preserves that job while making the trigger, open state, close path, and responsive behavior observable to users.

Know when the label is wrong

The fastest way to identify a pattern is often to reject the nearest alternative. For Toggle Button, the boundary is: If the control represents an on or off setting rather than a button-owned mode, use a Switch; if it selects form values, use Checkbox or Radio Group semantics.

Do not implement it as a Switch for toolbar actions, a Checkbox for a pressed command state, or a changing button label that hides the persistent pressed contract If those requirements describe the real task better, use the related pattern page or the full Choice and binary state controls comparison before writing code.

Decision process

Decide before choosing a component

Record these requirements in plain language. A library component name is not a substitute for the contract.

Confirm the user job

Keep a reversible button-controlled mode visibly and programmatically pressed until it is turned off.

Define opening and closing

Pointer activation, Enter, or Space while the button has focus. There is no open surface; activating again changes the pressed state when the action is reversible.

Specify access behavior

Focus remains on the button after activation unless the action intentionally moves it elsewhere. Enter and Space activate the button and update its pressed state.

Reject the near miss

a Switch for toolbar actions, a Checkbox for a pressed command state, or a changing button label that hides the persistent pressed contract

Behavior contract

What must survive the build

trigger: Pointer activation, Enter, or Space while the button has focus.
dismissal: There is no open surface; activating again changes the pressed state when the action is reversible.
modality: Inline and non-modal.
focus: Focus remains on the button after activation unless the action intentionally moves it elsewhere.
keyboard: Enter and Space activate the button and update its pressed state.
interactive: The element remains a button and exposes pressed state through aria-pressed when native semantics do not provide it.
persistence: Pressed state remains until the user or application turns the mode off.
placement: Often appears in a toolbar or beside controls affected by the active mode.
mobile: Make pressed and not pressed states visible without color alone and keep the button target large enough to operate.
state: Pressed or not pressed, exposed with aria-pressed while the accessible label remains stable.
choice: Activates or deactivates a button-owned mode or state rather than selecting a form value.
grouping: Independent toggle buttons need no shared selection contract; grouped toggles require separate group rules outside this pilot.

Failure modes

Common wrong builds

Changing the label instead of exposing pressed state.
Using aria-pressed on an ordinary one-time action button.
Showing pressed state only through color.

Observable checks

Verify the result

Enter and Space activate the button.
The accessible pressed state matches the visible state.
The accessible label remains stable as pressed state changes.
A one-time action button does not receive aria-pressed.
Pressed state is visible without relying only on color.
Focus remains predictable after activation.

Coding-agent handoff

Implementation brief template

Pattern: Toggle Button
Purpose: Keep a reversible button-controlled mode visibly and programmatically pressed until it is turned off.
Trigger: Pointer activation, Enter, or Space while the button has focus.
Dismissal behavior: There is no open surface; activating again changes the pressed state when the action is reversible.
Modality: Inline and non-modal.
Focus behavior: Focus remains on the button after activation unless the action intentionally moves it elsewhere.
Keyboard behavior: Enter and Space activate the button and update its pressed state.
Interactive content: The element remains a button and exposes pressed state through aria-pressed when native semantics do not provide it.
Placement: Often appears in a toolbar or beside controls affected by the active mode.
Mobile behavior: Make pressed and not pressed states visible without color alone and keep the button target large enough to operate.
Do not implement as: a Switch for toolbar actions, a Checkbox for a pressed command state, or a changing button label that hides the persistent pressed contract
Acceptance checks:
- Enter and Space activate the button.
- The accessible pressed state matches the visible state.
- The accessible label remains stable as pressed state changes.
- A one-time action button does not receive aria-pressed.
- Pressed state is visible without relying only on color.
- Focus remains predictable after activation.

Claim-level references

Sources, not a confidence score

01Button PatternW3C WAI-ARIA Authoring Practices · Official accessibility guidance

Toggle button pressed state, stable label, aria-pressed, Space, and Enter behavior

Frequently asked questions

Toggle Button UI pattern questions

Direct answers based on the reviewed behavior contract above.

What is a Toggle Button in web UI?

A button that stays pressed or not pressed to represent a persistent mode or state while retaining button semantics. In this reference set it is a behavior variant that normally modifies another control rather than defining a complete component by itself.

When should I use a Toggle Button?

Keep a reversible button-controlled mode visibly and programmatically pressed until it is turned off. The decisive boundary to confirm is this: If the control represents an on or off setting rather than a button-owned mode, use a Switch; if it selects form values, use Checkbox or Radio Group semantics.

What keyboard and focus behavior does a Toggle Button need?

Enter and Space activate the button and update its pressed state. Focus remains on the button after activation unless the action intentionally moves it elsewhere. These statements describe the reviewed expectation, but the final implementation still needs testing in the component library and browser you ship.

How should a Toggle Button behave on mobile?

Make pressed and not pressed states visible without color alone and keep the button target large enough to operate. Its modality is a separate requirement: Inline and non-modal.

How do I verify a Toggle Button implementation?

Start with observable checks: Enter and Space activate the button. The accessible pressed state matches the visible state. The accessible label remains stable as pressed state changes. Then verify the remaining checks and compare the result with the linked source guidance.