Switch

v0.8.0
@ui5/webcomponents
<ui5-switch>

Basic Switch

<ui5-switch text-on="On" text-off="Off"></ui5-switch>
<ui5-switch text-on="On" text-off="Off" checked></ui5-switch>
<ui5-switch></ui5-switch>
<ui5-switch checked></ui5-switch>
<ui5-switch text-on="Yes" text-off="No" disabled></ui5-switch>
<ui5-switch text-on="Yes" text-off="No" checked disabled ></ui5-switch>
	

Graphical Switch

<ui5-switch accessible-name="graphical" design="Graphical"></ui5-switch>
<ui5-switch accessible-name="graphical" design="Graphical" checked></ui5-switch>
<ui5-switch accessible-name="graphical" design="Graphical" disabled></ui5-switch>
<ui5-switch accessible-name="graphical" design="Graphical" checked disabled></ui5-switch>
	

Overview

The ui5-switch component is used for changing between binary states.
The component can display texts, that will be switched, based on the component state, via the textOn and textOff properties, but texts longer than 3 letters will be cutted off.
However, users are able to customize the width of ui5-switch with pure CSS (<ui5-switch style="width: 200px">), and set widths, depending on the texts they would use.
Note: the component would not automatically stretch to fit the whole text width.

Keyboard Handling

The state can be changed by pressing the Space and Enter keys.

CSS Shadow Parts

CSS Shadow Parts allow developers to style elements inside the Shadow DOM.
The ui5-switch exposes the following CSS Shadow Parts:
  • slider - Used to style the track, where the handle is being slid
  • text-on - Used to style the textOn property text
  • text-off - Used to style the textOff property text
  • handle - Used to style the handle of the switch

ES6 Module Import

import "@ui5/webcomponents/dist/Switch";

Properties/Attributes

You can use both properties and attributes with the same effect. The name of each attribute is listed below the name of the property, if different.

Name
Type
Default Value
Description
accessibleName
accessible-name
string
Sets the accessible aria name of the component. Note: We recommend that you set an accessibleNameRef pointing to an external label or at least an accessibleName. Providing an accessibleNameRef or an accessibleName is mandatory in the cases when textOn and textOff properties aren't set.
since v1.2.0
accessibleNameRef
accessible-name-ref
string
""
Receives id(or many ids) of the elements that label the component. Note: We recommend that you set an accessibleNameRef pointing to an external label or at least an accessibleName. Providing an accessibleNameRef or an accessibleName is mandatory in the cases when textOn and textOff properties aren't set.
since v1.1.0
checked
boolean
false
Defines if the component is checked.

Note: The property can be changed with user interaction, either by cliking the component, or by pressing the Enter or Space key.
design
SwitchDesign
"Textual"
Defines the component design.

Note: If Graphical type is set, positive and negative icons will replace the textOn and textOff.
disabled
boolean
false
Defines whether the component is disabled.

Note: A disabled component is noninteractive.
textOff
text-off
string
""
Defines the text, displayed when the component is not checked.

Note: We recommend using short texts, up to 3 letters (larger texts would be cut off). Note: This property will have no effect if the theme is set to sap_horizon.
textOn
text-on
string
""
Defines the text, displayed when the component is checked.

Note: We recommend using short texts, up to 3 letters (larger texts would be cut off). Note: This property will have no effect if the theme is set to sap_horizon.

Events

This Web Component fires semantic events upon user interaction. You can bind to these events with the standard DOM APIs, such as addEventListener.

Name
Description
change
Fired when the component checked state changes.
Theme: Quartz Light Quartz Dark Quartz High Contrast Black Quartz High Contrast White Morning Horizon (Light) Evening Horizon (Dark) Horizon High Contrast Black Horizon High Contrast White Belize
Content Density: Cozy Compact
Text Direction: LTR RTL
Apply Cancel