Updated: November 9, 2023

Switch

sap.m.Switch

Intro

The toggle switch mimics a physical switch. It allows users to set individual features (such as personalization or display settings) to either active or inactive.

Label, optional text, and switch
Label, optional text, and switch

Usage

Use the switch if:

  • You want to enable users to set something as active or inactive (for example, within a dialog).
  • You need to clearly show the mode or state of a setting.
  • The change takes immediate effect.

Do not use the switch if:

  • The user has to choose several options or perform extra steps for changes to become effective.
  • It’s not clear if the control is showing a state or an action. In this case, use a checkbox instead.

Types

There are three switch types: basic, semantic, and with optional text.

Basic Switch (Default)

The basic switch changes something to active or inactive. This is the default switch.

Default switch
Default switch

Semantic Switch

The semantic switch changes something to ‘positive’ or ‘negative’. An icon is displayed automatically for each semantic state and cannot be changed.

Semantic switch
Semantic switch

Switch with Optional Text

You can display a text (sap.m.text or sap.m.objectstatus) next to the switch to indicate what the ‘active’ and ‘inactive’ states mean in your specific use case. Keep the text succinct.

Position the text next to the switch:

  • Left of the switch in left-to-right writing systems
  • Right of the switch in right-to-left writing systems
Switch with optional text
Switch with optional text
Semantic switch with optional text
Semantic switch with optional text

Don't
Switch containing text
Switch containing text

Behavior and Interaction

The control supports mouse, touch, keyboard and screen reader interaction.

The user can switch between two states: active or inactive. The state is changed by moving the toggle from one side to another or by clicking the empty side. The toggle then moves over.

Styles

Switches can have different states and markups, but are always ‘active’ or ‘inactive’. The control supports an enabled, hovered, and disabled state.

Enabled semantic switch
Enabled semantic switch
Hovered semantic switch
Hovered semantic switch
Disabled semantic switch
Disabled semantic switch

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation