The switch is available in sizes 50 and 100. There is also a loading variant for actions that take longer. When checked, the background color changes and the handle displays a check icon.
Users can check the switches by tapping anywhere on it. The label is also part of the hitbox and ensures proper support in assistive technologies, improving usability and accessibility. To uncheck the switch, it may be tapped again. There is also a disabled variant that cannot be clicked or tapped.
The width of the switch is set to fit-content by default, but can be set to fill-parent. Note, that the whole line is interactive in this case. The height of the label is set to fit-content.
width-behavior fit
width-behavior fill
LivefittingHTML
<p class="demo-label">width-behavior fit</p>
<oc-switch-v3><input type="checkbox" aria-label="oc-auto"><label slot="label">Label</label></oc-switch-v3>
<p class="demo-label">width-behavior fill</p>
<oc-switch-v3 width-behavior="fill"><input type="checkbox" aria-label="oc-auto"><label slot="label">hier steht ein sehr, sehr, sehr, sehr langes Label</label></oc-switch-v3>
Placement
The switch has a mandatory label which can be placed left or right. Ideally, there should be a 24px gap between switches if they are placed vertically. When placing multiple switches vertically, make sure to align them properly.
Use the switch for immediate actions, such as toggling a setting on or off. The action happens the moment the user interacts with it.
Use the checkbox when a separate interaction is needed to confirm a choice, such as "Speichern" or "Bestätigen", or when multiple options can be selected simultaneously as part of a larger form.
Checkbox: confirmed with a button
Weiter
Switch: takes effect at once
Livesingle selection on desktop and mobileHTML
<p class="demo-label">Checkbox: confirmed with a button</p>
<oc-checkbox-v2><input type="checkbox" checked aria-label="oc-auto"><label slot="label">Ich möchte den OTTO-Newsletter erhalten.</label></oc-checkbox-v2>
<oc-button-v1 variant="primary">Weiter</oc-button-v1>
<p class="demo-label">Switch: takes effect at once</p>
<oc-switch-v3><input type="checkbox" checked aria-label="oc-auto"><label slot="label">OTTO-Newsletter erhalten</label></oc-switch-v3>
Do not use switches for lists consisting of multiple options. Instead, use checkboxes. Checkboxes imply that the items are related and take up less visual space than switches.
Don'tUse Switches for toggling between opposite options.
Don'tNest switches.
Content guidelines
DoUse short, precise labels to describe the options.Don'tUse overly descriptive labels.Don'tUse on or off for the label.DoUse Sentence case (Großschreibung) for labels.
Accessibility
For information on accessibility, refer to the technical documentation.
Only the latest version (v3) is allowed for generation. Older versions are kept for reference and are deprecated.
Overview (v3)
Switch
The switch component toggles a binary state such as notifications, privacy settings, or feature flags.
It exposes a slotted input type="checkbox" for native form participation and an optional label slot for context.
The switch component is available in the main styling variants ..
This component is configurable, allowing you to tailor its features and appearance to your specific needs.
To explore all the available options and adjust the component, use the component configurator and see the changes affect the component in real-time.
Usage guidelines
Before integrating the switch component into your project, make sure you have correctly installed the OTTO components package.
Look through the variations page for examples of possible component variations.
Here, you can discover both common and specific variations that address different use cases.
Accessibility
The switch component depends on the attributes applied to the slotted input, so include either visible text via the default slot or an aria-label on the input.
Propagate disabled, checked, and required to the native control, and expose aria-live messaging externally when relying on the loading state.
Reference the built-in accessibility features guide for keyboard support.
Configuration (v3)
Switch configuration
Configure the switch component with the controls below and see the changes live in the preview canvas.
Click the Show code button within the preview canvas to see the source code for the current component configuration.
Interactive configurator (Storybook controls); every option is listed in the API section of this file.
Migration (v3)
Migration from switch v2 to v3
The oc-switch component has been updated from oc-switch-v2 to oc-switch-v3.
This migration guide provides step-by-step instructions to update your project to the latest version.
Now contains the native <input type="checkbox"> element
Removed attributes
The following attributes have been removed and should now be set on the native <input> element:
v2 Attribute
v3 Equivalent
Notes
checked
Set checked on the <input> element
Moved to native input
disabled
Set disabled on the <input> element
Moved to native input
name
Set name on the <input> element
Moved to native input
value
Set value on the <input> element
Moved to native input
oc-aria-label
Set aria-label on the <input> element
Renamed to standard attribute
How to migrate
The main change is that v3 uses a native <input type="checkbox"> element in the default slot instead of managing the switch state internally.
This provides better accessibility, form integration, and native event support.
The switch component provides a toggle functionality.
It has attributes for setting the initial checked state, a disabled state, the value to submit if checked, the name of the input element, the label placement, and the size of the switch.
The switch can be initialized as checked or unchecked, and it has a loading state that can be toggled on or off.
Attributes / properties
Attribute
Type
Default
Required
Description
size
"50" | "100"
"100"
no
Sets the size of the switch.
value
string
"on"
no
Sets the initial value of the switch to the provided value for form processing. This is also the reset value for a form reset. If omitted, the default value for the switch is on.
checked
boolean
false
no
Toggles the state of the switch between checked and unchecked. Set to true to enable the checked state.
Accessible in CSS via the custom-state mixin.
disabled
boolean
false
no
Disables the switch, preventing user interaction. Set to true to disable the switch.
loading
boolean
false
no
Toggles the state of the button between loading and not loading. Set to true to enable the loading state and display a loading animation.
fit-content
boolean
false
no
Sets the width of the switch to fit its content.
name
string
no
Sets the name to identify the switch when submitting a form.
label-placement
"left" | "right"
"right"
no
Sets the placement direction of the label provided via the default slot relative to the switch.
oc-aria-label
string
undefined
no
Sets the ARIA label of the switch.
Slots
Slot
Required
Description
default
no
Sets the label of the switch element. Change the location of the label by setting the label-placement attribute. By default it will appear on the right side of the switch.
Events
Event
Detail type
Description
oc-property-change
OcSwitchV2Events["oc-property-change"]
Whenever a property value changes, this event triggers. Use this event to track all property changes within the component.
Fired when the component is mounted to the DOM. The event is fired when the onMount hook of the component is called by the runtime.
oc-unmount
{ component: string; }
Fired when the component is unmounted from the DOM. The event is fired when the function returned by the onMount hook of the component is called by the runtime.
API v3
Switch v3 API
API: <oc-switch-v3> (SwitchV3)
The Switch component allows users to toggle between two states (on and off).
Provides configurable label placement, size, loading state, and slots for the label and input element.
Attributes / properties
Attribute
Type
Default
Required
Description
size
"50" | "100"
"100"
no
The size of the switch.
loading
boolean
false
no
Indicates whether the switch displays a loading state. When true, shows a loading animation. When false, displays the normal switch state.
width-behavior
"fill" | "fit"
"fit"
no
Defines the width behavior of the switch component. - "fill": The component expands to fill the available width. - "fit": The component width fits its content.
label-placement
"left" | "right"
"right"
no
The placement direction of the label provided via the default slot relative to the switch indicator.
The label text of the switch element. The label location can be changed using the label-placement attribute. By default, the label appears on the right side of the switch.
Events
Event
Detail type
Description
oc-property-change
OcSwitchV3Events["oc-property-change"]
Whenever a property value changes, this event triggers. Use this event to track all property changes within the component.
Fired when the component is mounted to the DOM. The event is fired when the onMount hook of the component is called by the runtime.
oc-unmount
{ component: string; }
Fired when the component is unmounted from the DOM. The event is fired when the function returned by the onMount hook of the component is called by the runtime.
Variations (v3)
Variations
Listed below are the most common variations of the switch component as well as specific component variations for different use cases.
You can explore all available options using the component configurator, adjust the component to your needs, and see the changes live in a preview canvas.
Displays a visible label passed via the default slot.
The label-placement attribute controls whether the label appears on the left or right side of the switch.
The switch component provides a toggle functionality within a form.
It has attributes for setting the initial checked state, a disabled state, the value to submit if checked, the name of the input element, the label placement, and the size of the switch.
The switch can be initialized as checked or unchecked, and it has a loading state that can be toggled on or off.
The switch component offers the styling variants rectangular and circular.
This component is configurable, allowing you to tailor its features and appearance to your specific needs.
To explore all the available options and adjust the component, use the component configurator and see the changes affect the component in real-time.
Usage guidelines
Before integrating the switch component into your project, make sure you have correctly installed the OTTO components package.
Look through the variations page for examples of possible component variations. Here, you can discover both common and specific variations that address different use cases.
Important
If the switch component is used in a form, pressing Enter while focused on the switch triggers the submit action immediately (implicit submit) if an oc-button component or a normal HTML button with the type submit is also present in the form.
To make the switch recognizable for screen readers, use the default slot to provide a clear and descriptive label.
Use the aria-label attribute on the label to provide additional context if the visible label is not sufficient.
See the general accessibility documentation for guidance on using oc-aria-label, including how it works with link and masked link behavior.
aria-checked
The switch component automatically handles the aria-checked attribute.
The aria-checked attribute indicates the current "checked" state of the switch component.
Keyboard navigation
The switch component supports keyboard navigation for accessibility purposes.
The following table lists the keyboard shortcuts available for this component:
V2/Configuration (v2, deprecated, not for generation)
Switch V2 configuration
Configure the switch component with the controls below and see the changes live in the preview canvas.
Click the Show code button within the preview canvas to see the source code for the current component configuration.
V2/Variations (v2, deprecated, not for generation)
Variations
Listed below are the most common variations of the switch component as well as specific component variations for different use cases.
You can explore all available options using the component configurator, adjust the component to your needs, and see the changes live in a preview canvas.
The default configuration has size=100 and has no label. Instead of a label, it uses the oc-aria-label attribute to describe the purpose of the switch.
Variation of the switch with a visible label passed via the default slot and using the label-placement attribute to place the label to the right of the switch.
<oc-switch-v2 checked label-placement="left">switch</oc-switch-v2>
<p>
the background is red, when the modern syntax<br /><code
>oc-switch-v2:state(checked) {}</code
>
applies
</p>
<p>
for demo purpose, it is yellow in older browsers
<br /><code>oc-switch-v2[state--checked] {}</code>
</p>
<style>
/* Unknown pseudo selector 'state'?, You are wrong IntelliJ, that is valid
https://developer.mozilla.org/en-US/docs/Web/CSS/:state
*/
oc-switch-v2:state(checked) {
background-color: #f00;
}
/* in older browsers, this is done by a mixin packages/otto-components-utils/scss/_mixins/custom-state.scss */
oc-switch-v2[state--checked] {
background: yellow;
}
</style>
Story source (TypeScript, verbatim from Storybook)
{
name: "Demo: exposed state",
argTypes: hideControlsBadge(Metadata),
parameters: {
controls: {
disabled: true
},
// Disables Chromatic's snapshotting, as the spinner is animated und thus leads to diffs
chromatic: {
disableSnapshot: true
}
},
render: () => {
return html` <oc-switch-v2 checked label-placement="left">switch</oc-switch-v2>
<p>
the background is red, when the modern syntax<br /><code
>oc-switch-v2:state(checked) {}</code
>
applies
</p>
<p>
for demo purpose, it is yellow in older browsers
<br /><code>oc-switch-v2[state--checked] {}</code>
</p>
<style>
/* Unknown pseudo selector 'state'?, You are wrong IntelliJ, that is valid
https://developer.mozilla.org/en-US/docs/Web/CSS/:state
*/
oc-switch-v2:state(checked) {
background-color: #f00;
}
/* in older browsers, this is done by a mixin packages/otto-components-utils/scss/_mixins/custom-state.scss */
oc-switch-v2[state--checked] {
background: yellow;
}
</style>`;
}
}