This guideline now covers both SAPUI5 and SAP Web Components. Learn more.
Information
Icon
false

Intro

The toggle button is a UI component that switches between two states: active and inactive.

Use the toggle button for secondary actions like showing or hiding a screen element or providing a filtered view of a dataset.

Toggle Button examples showing text and icon-only variants in default (unselected) and selected states.

Toggle button

Component availability

The toggle button is available in the following libraries:

<div> <div data-valign="middle">Library</div> <div data-valign="middle">Technical Name</div> <div data-valign="middle">Identifier</div> </div> <div> <div data-valign="middle">SAPUI5 Demo Kit</div> <div><a href="https%3A%2F%2Fui5.sap.com%2F%23%2Fentity%2Fsap.m.ToggleButton">sap.m.ToggleButton</a></div> <div data-valign="middle">:badge, info, large, _, SAPUI5:</div> </div> <div> <div data-valign="middle">SAP Web Components</div> <div data-valign="middle"><a href="https%3A%2F%2Fui5.github.io%2Fwebcomponents%2Fcomponents%2FToggleButton%2F">ui5-toggle-button</a></div> <div data-valign="middle">:badge, info, large, _, SAP Web Components:</div> </div> <div> <div data-valign="middle">SAP Web UI Kit (Figma)</div> <div data-valign="middle"><a href="https%3A%2F%2Fwww.figma.com%2Fdesign%2FSILcWzK5uFghKun9jx6D7c%2FSAP-Web-UI-Kit%3Fnode-id%3D365511-5609%26t%3DE4ejx9oEHVg9l0a5-4">Toggle Button</a></div> <div data-valign="middle">:badge, info, large, _, Figma:</div> </div>
<div> <div data-valign="middle">Library</div> <div data-valign="middle">Technical Name</div> <div data-valign="middle">Identifier</div> </div> <div> <div data-valign="middle">SAPUI5 Demo Kit</div> <div><a href="https%3A%2F%2Fui5.sap.com%2F%23%2Fentity%2Fsap.m.ToggleButton">sap.m.ToggleButton</a></div> <div data-valign="middle">:badge, info, large, _, SAPUI5:</div> </div> <div> <div data-valign="middle">SAP Web Components</div> <div data-valign="middle"><a href="https%3A%2F%2Fui5.github.io%2Fwebcomponents%2Fcomponents%2FToggleButton%2F">ui5-toggle-button</a></div> <div data-valign="middle">:badge, info, large, _, SAP Web Components:</div> </div> <div> <div data-valign="middle">SAP Fiori for Web UI Kit (Figma)</div> <div data-valign="middle"><a href="https%3A%2F%2Fwww.figma.com%2Fcommunity%2Ffile%2F1494295794601744471">Toggle Button</a></div> <div data-valign="middle">:badge, info, large, _, Figma:</div> </div>

When to Use

2
do
false

Use the toggle button to:

  • Switch between two states.
  • Activate or deactivate an element in a toolbar.
dont
false

Don’t use the toggle button to:

  • Trigger an activity, flow, or process (such as Create, Edit, or Save). Use a button instead.
  • Display a large number of options. Use a menu button instead.
  • Use the standard toggle button for secondary actions.
  • Use the transparent toggle button for tertiary actions.
  • Always pair icon-only toggle buttons with a tooltip that labels them.

Anatomy

The toggle button component consists of the following elements:

  1. Background: Different background colors indicate the state of the toggle button.
  2. Text or icon: Describes or visualizes the action triggered by the toggle button.

Anatomy of a toggle button with numbered pointers for background and text.

Toggle button anatomy

Types

Display types

The toggle button supports three display types:

A: Text only
B: Icon only
C: Text and icon

Toggle button types: text (A), icon (B), icon and text (C).

Display types

Hierarchy types

The toggle button has two hierarchy types:

A. Standard: The standard toggle button appears with a white background and subtle gray border and is used for secondary actions.
B. Transparent: The transparent toggle button appears with a transparent background and no border and is used for tertiary actions.

Toggle Button hierarchy types: standard with white background and gray border (A) and transparent with no border (B).

Hierarchy types

States

Component states

The toggle button supports two component states: enabled and disabled. Each state can appear as untoggled or toggled.

A. Enabled: The toggle button is interactive, enabling the user to select it and trigger its associated action.
B. Disabled: The toggle button is not interactive and cannot be selected or triggered by the user.

Toggle Button component states: enabled (A) and disabled (B), each shown in untoggled and toggled variants.

Component states: enabled (A) and disabled (B)

For more information, see Component States.

Interaction states

The toggle button supports three interaction states: regular, hover, and down. Each state appears as untoggled or toggled.

Regular states

A. Regular untoggled: Displays the default, unselected state.
B. Regular toggled: Displays the selected state.

Toggle Button regular states: untoggled (A) and toggled (B).

Regular states: untoggled (A) and toggled (B)

Hover states

A. Hover untoggled: Displays a hover state when the cursor moves over an enabled, unselected toggle button.
B. Hover toggled: Displays a hover state when the cursor moves over an enabled, selected toggle button.

Toggle Button hover states: untoggled on hover (A) and toggled on hover (B).

Hover states: untoggled on hover (A) and toggled on hover (B)

Down state

Down untoggled: Displays a down state while the user is pressing an unselected toggle button.

Toggle Button down state: untoggled while pressed.

Down untoggled state

For more information, see Interaction States.

Focus state

The focus state indicates that the toggle button is focused and displays a visible focus highlight.

The focus state appears with an additional border.

When interaction begins, the focus state appears on the active toggle button.

Toggle button focus state: focused untoggled (A) and focused toggled (B), each shown with an additional focus border.

Focused untoggled (A) and focused toggled (B) states

For more information, see Focus States.

Behavior and Interaction

Mouse interaction

Toggling a toggle button

Clicking an untoggled toggle button switches it to the toggled state.

A: The user starts pressing an untoggled toggle button.
B: When the user releases the toggle button, it toggles, triggers its action, and retains focus.
C: After the user moves the cursor away from the toggle button, it becomes regular toggled.

Toggle button interaction sequence: press (A), release to toggle and retain focus (B), and regular toggled state after hover ends (C).

Toggling interaction

Untoggling a toggle button

Clicking a toggled toggle button switches it to the untoggled state.

Touch interaction

On touch devices, tapping the toggle button toggles its state. Hover and focus states are not supported.

Tooltips

When designing icon-only toggle buttons, always pair them with a tooltip that labels them.

Icon-only toggle button displaying a tooltip label on hover.

Icon-only toggle button with tooltip

For more information, see Using Tooltips.

Responsiveness

By default, the toggle button expands and shrinks with the width of the text or icon.

Toggle button in 3 variants—icon-only, text-only, and icon plus text—each with a fitting button width.

Toggle button with different lengths

The toggle button supports cozy and compact content densities.

Toggle button in compact (A) and cozy (B) content densities, showing different vertical spacing and height.

Compact (A) and cozy (B) content densities

For more information, see Content Density.

Accessibility

SAP follows international standards, such as WCAG and WAI-ARIA, and strives to make our business solutions accessible and inclusive.

For more information, see Accessibility in SAP Fiori and the Accessibility Design Tools Handbook.

Keyboard navigation

The following keyboard combinations are supported by the SAPUI5 Toggle Button component.

<div> <div>Key Combination</div> <div>What it Does</div> </div> <div> <div><strong>Tab</strong></div> <div>Moves the focus to the toggle button. If the focus is already there, the focus is moved to the next UI element.</div> </div> <div> <div><strong>Shift + Tab</strong></div> <div>Backward navigation.</div> </div> <div> <div><strong>Enter/ Return</strong> or <strong>Spacebar</strong></div> <div>Toggles the button's state.</div> </div>

Screen reader support

For additional details on screen reader support and Accessible Rich Internet Applications (ARIA), see UI5 Screen Reader Support and WAI-ARIA Authoring.

Content

Localization

The toggle button supports left-to-right (LTR) and right-to-left (RTL) reading directions.

Toggle button in left-to-right (LTR) layout, with a left-aligned icon followed by text.

Toggle button – left-to-right

Toggle button in right-to-left (RTL) layout, with a right-aligned icon followed by text.

Toggle button – right-to-left

Framework Comparison

There are no differences between SAPUI5 and SAP Web Components regarding thе component's behaviors and framework-specific patterns.

Guidelines

Components
Button

Implementation

SAPUI5
Toggle Button (samples)
Toggle Button (API reference)

SAP Web Components
Toggle Button

Specifications

Toggle Button (visual design)

SAP Web UI Kit

Toggle Button

Guidelines

Components
Button

Implementation

SAPUI5
Toggle Button (samples)
Toggle Button (API reference)

SAP Web Components
Toggle Button

UI Kit (Figma)

SAP Fiori for Web UI Kit / Toggle Button