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

Intro

The switch is a UI component used to toggle a setting on or off with a button. It lets users turn individual features on or off to adjust display settings or personalize the application’s appearance.

Switch with label showing one switch in the off state in gray and one switch in the on state in blue with a check mark.

Switch with label

Component availability

This component 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.Switch">sap.m.Switch</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%2FSwitch%2F">ui5-switch</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%3D19-2027">Switch</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.Switch">sap.m.Switch</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%2FSwitch%2F">ui5-switch</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%2Fsap-fiori-for-web-ui-kit">Switch</a></div> <div data-valign="middle">:badge, info, large, _, Figma:</div> </div>

When to Use

2
do
false

Use the switch to:

  • Set a setting as active or inactive (for example, in a dialog).
  • Clearly show the current mode or state of a setting.
  • Apply changes that take effect immediately.
dont
false

Don't use the switch to:

  • Allow selection of multiple options or require extra steps for changes to take effect.
  • Show a state or action when it's unclear which one the component is displaying. Use a checkbox instead.
  • Include text inside the switch component, as this can cause localization issues.
  • Use a default switch when you need a simple on/off component with predefined icons and standard colors.
  • Use a semantic switch when the action represents a positive or negative state.
  • Add a descriptive label either above or directly before a switch component. This helps users understand which value or feature it controls.
  • If the main label doesn't fully explain what "active" and "inactive" mean in your context, add a short text element (such as "On"/"Off" or status by using text or object status) next to the switch to clarify.

Anatomy

The switch consists of a background track and a movable handle.

  1. Track: Displays the container for the handle.
  2. Handle: Indicates whether the switch is on or off, depending on its position within the track.

Anatomy of a switch component showing track (1) and handle (2).

Switch anatomy

Types

There are four switch types: default, semantic, switch with label, and switch with optional text. While switches don’t typically support value states, the semantic type uses color to add specific meaning to the on or off states.

Default switch

The default switch type uses an icon inside the handle and the default colors for on or off states.

Default switch showing off and on states with icons inside the handle, using different colors – gray and blue.

Default switch

Semantic switch

The semantic switch represents a positive or negative status by using specific colors instead of the default ones: green indicates the positive (on) state, and red indicates the negative (off) state. Each semantic state also displays a system-defined icon that cannot be changed.

Semantic switch showing negative and positive states with icons inside the handle, using red and green colors.

Switch with semantic colors

Switch with label

Make it clear what value or feature the switch controls by placing a label above or before the switch. For example, “Enable Notifications” or “Receive Updates”.

Default switch in gray with labels placed above and next to the switch.

Switch with label

Switch with optional text

Add optional text after the switch to explain what “active” and “inactive” mean for the specific use case. Keep the text short, ideally a single word.

Gray inactive switch and blue active switch with label “Notifications” above them and optional text “Off” and “On” shown next to each.

Switch with label and optional text

States

States define how components look and behave in different scenarios, helping users predict interaction outcomes.

Component states

The switch has two component states – enabled and disabled. When enabled, the switch is interactive and can be toggled. When disabled, the switch is not interactive and only displays its current value, either unselected (off) or selected (on).

A. Enabled state: The switch is interactive and the user can turn it on or off.

B. Disabled state: The switch is not interactive, but remains visible so the user can view its current state.

Switch component states showing (A) enabled state with interactive toggles that can be turned on or off, and (B) disabled state with visible, non-interactive toggles.

Enabled and disabled switch component states

For more information, see Component States.

Interaction states

The switch has two interaction states – regular and hover. The regular and hover interaction states are supported in both the on and off modes.

A: Regular state: The default state of the component.

B: Hover state: The state when the cursor is positioned over the switch.

Regular and hover interaction states showing switches in default appearance and with a slightly thicker border on hover.

Regular and hover switch interaction states

For more information, see Interaction States.

Focus state

The focus state indicates which component is currently in focus.

A: Unfocused state: The switch is not in focus and does not display a focus indicator.

B: Focused state: The switch displays an additional border around the track to indicate focus.

Unfocused and focused switch states showing switches in default appearance and with an additional outer border to indicate focus.

Unfocused and focused switch states

For more information, see Focus States.

Behavior and Interaction

The switch toggles between on and off when the user clicks or taps it. Visual feedback updates immediately to reflect the new state. The component supports interaction through mouse, touch, and keyboard.

Turning a switch on or off

A switch toggles between on and off states through user interaction. The component supports multiple interaction methods:

When toggled, the switch updates its visual appearance with a new color, icon, and handle position. A focus indicator appears during keyboard or interaction focus.

Sequence showing mouse interaction turning a switch from gray off state to blue on state.

Turning switch on

Note: Hover states are not supported on touch devices. For more information, see tap gesture and drag gesture.

Tooltips

Provide a tooltip when no label is available to give context for the switch. The label identifies what the switch controls and the effect of toggling it.

Sequence showing a switch without a tooltip, then on mouse hover displaying a tooltip with contextual text.

Switch with tooltip

Responsiveness

The switch does not adapt responsively, but it supports two content density modes depending on the device:

Switch in compact mode (smaller size) and cozy mode (larger size), each shown in default and active states.

Switch in compact and cozy modes

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 Switch component.

<div> <div>Key Combination</div> <div>What it Does</div> </div> <div> <div><strong>Tab</strong></div> <div>Focus goes to the switch.</div> </div> <div> <div><strong>Shift + Tab</strong></div> <div>Navigates backward.</div> </div> <div> <div><strong>Spacebar or Enter/Return</strong></div> <div>Toggles between the different states of the switch.</div> </div>

Screen reader support

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

Content

Localization

The switch component supports both left-to-right (LTR) and right-to-left (RTL) reading directions.

Switch in left-to-right mode with label on the left and switch on the right, shown in default and active states.

Switch in left-to-right mode

Switch in right-to-left mode with label on the right and switch on the left, shown in default and active states.

Switch in right-to-left mode

Wrapping and Truncation

By default, label text wraps automatically. Use truncation only when space is limited. Apply a hybrid approach when needed: allow the label to wrap for up to N lines, then truncate any remaining text. Keep labels concise, and reserve truncation for edge cases when no other option is available.

For more information, see Wrapping & Truncation.

Label on top

For top labels, when the text wraps, the switch is pushed down by the additional lines. The number of wrapped lines depends on the label’s length.

Sequence showing a switch with a top label wrapping onto more lines as the container width decreases, pushing the switch downward.

Switch with top label wrapping

Label and optional text

By default, the optional text wraps. Avoid truncation and keep both the label and optional text short and concise.

Sequence showing a switch with label above it and optional text beside it, wrapping onto multiple lines and eventually truncating as the container width decreases.

Switch with wrapping and truncation of optional text

Label to the side

When a side label cannot fit horizontally, the switch moves below the label. The text wraps by default.

Sequence showing a switch with a side label moving above the switch as the container width decreases, with the label wrapping and eventually truncating.

Switch with side label repositioning

Framework Comparison Overview

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

Guidelines

Components
Select
Radio Button
Checkbox

Implementation

SAPUI5
Switch (samples)
Switch (API reference)

SAP Web Components
Switch

Specifications

Switch (visual design)

SAP Web UI Kit
Switch

Guidelines

Components
Select
Radio Button
Checkbox

Implementation

SAPUI5
Switch (samples)
Switch (API reference)

SAP Web Components
Switch

UI Kit (Figma)

SAP Fiori for Web UI Kit / Switch