Switches
Switches are UI elements that toggle between two states, typically 'On' and 'Off', used to enable or disable features, options, or settings.
On this page
- Switch item v1.5.0
- Switch v1.5.0
Overview
Component types
- Switch item is a UI element shaped like a row that toggles between two states, typically "On" and "Off," and is used to enable or disable features, options, or settings.
- Switch is a UI element that toggles between two states, typically "On" and "Off," and is used to enable or disable features, options, or settings.
Switch item
Switch item is a UI element shaped like a row that toggles between two states, typically "On" and "Off," and is used to enable or disable features, options, or settings.
Unlike the standalone switch, the switch item accommodates a broader range of contexts by enabling the toggling of visibility of additional text labels and icon assets.
They are implemented using .switch-item and .control-item-* classes, see below. Browser default checkboxes are replaced with the help of .control-item-indicator[role="switch"].
<ul class="control-items-list">
<li class="switch-item">
<div class="control-item-assets-container">
<input class="control-item-indicator" type="checkbox" role="switch" value="" id="switchItemDefault" />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemDefault">Default switch item</label>
</div>
</li>
<li class="switch-item">
<div class="control-item-assets-container">
<input checked class="control-item-indicator" type="checkbox" role="switch" value="" id="switchItemDefault2" />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemDefault2">Checked switch item</label>
</div>
</li>
</ul>
Bootstrap
$enable-bootstrap-compatibility: true
<div class="form-check form-switch">
<input class="form-check-input" type="checkbox" role="switch" id="switchItemCheckDefault" />
<label class="form-check-label" for="switchItemCheckDefault">Default switch item (Bootstrap compatible)</label>
</div>
<div class="form-check form-switch">
<input checked class="form-check-input" type="checkbox" role="switch" id="switchItemCheckChecked" />
<label class="form-check-label" for="switchItemCheckChecked">Checked switch item (Bootstrap compatible)</label>
</div>
Approach
Control item
Control item is an abstraction for several non-text input components, like checkbox item, radio button item and switch item, that have similar behavior and layout. It contains an <input /> indicator, a text container for the label and an optional icon.
We use the parent element selector (:has) for all our <input /> states, like :invalid or :disabled. When combined with the .control-item-label class, we can easily style the text for each item based on the <input />’s state.
.control-item-assets-container controls the position of the .control-item-indicator and the optional icon.
.control-item-text-container contains the label and optional description and controls their positioning.
.control-item-label extend their clickable area until a .checkbox-standalone, .radio-button-standalone, .switch-standalone or a position: relative; is found in the page hierarchy. This ensures a consistent approach, whatever the DOM is. Consequently, none of the elements next to the label should be interactive.
.control-item-indicator uses customized icons to indicate checked states.
Switch grouping and error handling
As switch items can be used inside a list or a form, but also in a standalone way, there are several ways to group them. You can use a <fieldset> container if they are in a form, with an optional <legend> (read more here), you can also use a <ul> (like most of the examples in this page). For both these solutions please add a .control-items-list class on the list container.
For automatic error handling on a single switch item, you need to surround it in a .switch-item-container, read more in the invalid state section.
Accessibility
Variants
Divider
To display a divider, add .control-item-divider to a .switch-item.
<ul class="control-items-list">
<li class="switch-item control-item-divider">
<div class="control-item-assets-container">
<input class="control-item-indicator" type="checkbox" role="switch" value="" id="switchItemDivider" />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemDivider">Default switch item with divider</label>
</div>
</li>
<li class="switch-item control-item-divider">
<div class="control-item-assets-container">
<input class="control-item-indicator" type="checkbox" role="switch" value="" id="switchItemDivider2" checked />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemDivider2">Checked switch item with divider</label>
</div>
</li>
</ul>
Icon
To display an icon, add .control-item-assets-container with an icon (SVG or font-icon most likely) inside, as a child of a .switch-item.
<ul class="control-items-list">
<li class="switch-item">
<div class="control-item-assets-container">
<input class="control-item-indicator" type="checkbox" role="switch" value="" id="switchItemWithSVG" />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemWithSVG">Default switch item with an SVG icon</label>
</div>
<div class="control-item-assets-container">
<svg aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#heart-empty" />
</svg>
</div>
</li>
<li class="switch-item">
<div class="control-item-assets-container">
<input class="control-item-indicator" type="checkbox" role="switch" value="" id="switchItemWithIconFont" checked />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemWithIconFont">Checked switch item with a font-icon</label>
</div>
<div class="control-item-assets-container">
<span class="icon si si-settings" aria-hidden="true"></span>
</div>
</li>
</ul>
Description text
To display a description text, add a .control-item-description as a sibling of a .control-item-label. Make sure the description is accessible by adding an aria-describedby attribute to the input.
-
Description text
-
Description text
<ul class="control-items-list">
<li class="switch-item">
<div class="control-item-assets-container">
<input class="control-item-indicator" type="checkbox" role="switch" aria-describedby="switchItemDescription" id="switchItemWithDescription" value="" />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemWithDescription">Default switch item</label>
<p class="control-item-description" id="switchItemDescription">Description text</p>
</div>
</li>
<li class="switch-item">
<div class="control-item-assets-container">
<input class="control-item-indicator" type="checkbox" role="switch" aria-describedby="switchItemDescription2" id="switchItemWithDescription2" value="" checked />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemWithDescription2">Checked switch item</label>
<p class="control-item-description" id="switchItemDescription2">Description text</p>
</div>
</li>
</ul>
States
Disabled
Add the disabled attribute to the input, then the switch indicator and the associated <label> are automatically styled to match with a lighter color to help indicate the input’s state.
<ul class="control-items-list">
<li class="switch-item">
<div class="control-item-assets-container">
<input disabled class="control-item-indicator" type="checkbox" role="switch" value="" id="switchItemDisabled" />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemDisabled">Default disabled switch item</label>
</div>
</li>
<li class="switch-item">
<div class="control-item-assets-container">
<input disabled class="control-item-indicator" type="checkbox" role="switch" value="" id="switchItemCheckedDisabled" checked />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemCheckedDisabled">Checked disabled switch item</label>
</div>
</li>
</ul>
Bootstrap
$enable-bootstrap-compatibility: true
<div class="form-check form-switch">
<input disabled class="form-check-input" type="checkbox" role="switch" id="switchItemCheckDisabled" />
<label class="form-check-label" for="switchItemCheckDisabled">Default disabled switch item (Bootstrap compatible)</label>
</div>
<div class="form-check form-switch">
<input disabled class="form-check-input" type="checkbox" role="switch" id="switchItemCheckCheckedDisabled" checked />
<label class="form-check-label" for="switchItemCheckCheckedDisabled">Checked disabled switch item (Bootstrap compatible)</label>
</div>
Read only
To create a read only switch item, the input should be replaced by a span element with role="switch", aria-readonly="true" and aria-disabled="true" attributes. The switch item will be accessible to keyboard navigation and assistive technologies thanks to aria-labelledby and tabindex, but other interactions will be prevented.
-
Default readonly switch item
-
Checked readonly switch item
<ul class="control-items-list">
<li class="switch-item">
<div class="control-item-assets-container">
<span class="control-item-indicator" role="switch" aria-readonly="true" aria-disabled="true" tabindex="0" aria-checked="false" aria-labelledby="switchItemReadonlyLabel"></span>
</div>
<div class="control-item-text-container">
<p class="control-item-label" id="switchItemReadonlyLabel">Default readonly switch item</p>
</div>
</li>
<li class="switch-item">
<div class="control-item-assets-container">
<span class="control-item-indicator" role="switch" aria-readonly="true" aria-disabled="true" tabindex="0" aria-checked="true" aria-labelledby="switchItemReadonlyCheckedLabel"></span>
</div>
<div class="control-item-text-container">
<p class="control-item-label" id="switchItemReadonlyCheckedLabel">Checked readonly switch item</p>
</div>
</li>
</ul>
Invalid
To manually mark a switch item as invalid, add aria-invalid="true" to a .control-item-indicator. An error icon will be automatically shown; if a decorative icon is specified, it will be hidden.
Error text on one switch item
To automatically display an error text on a single switch item, enclose it inside a .switch-item-container and add a .control-item-error-message as a sibling of the .switch-item.
Description text
<div class="switch-item-container">
<div class="switch-item control-item-divider">
<div class="control-item-assets-container">
<input class="control-item-indicator" aria-invalid="true" type="checkbox" role="switch" value="" id="switchItemInvalid" aria-describedby="switchItemInvalidDescription switchItemInvalidErrorText" checked />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemInvalid">Default invalid switch item</label>
<p class="control-item-description" id="switchItemInvalidDescription">Description text</p>
</div>
</div>
<p class="control-item-error-message" id="switchItemInvalidErrorText">Cannot be activated at this time.</p>
</div>
Bootstrap
$enable-bootstrap-compatibility: true
To display an invalid switch item, add .is-invalid to a .form-check-input.
<div class="form-check form-switch">
<input class="form-check-input is-invalid" type="checkbox" value="" id="switchItemCheckInvalid" role="switch" />
<label class="form-check-label" for="switchItemCheckInvalid">
Default invalid switch item (Bootstrap compatible)
</label>
</div>
To add an error message on a single switch item inside a list, the .switch-item should be inside a <li> with a .switch-item-container class. The error text will only be displayed when this particular switch item's .control-item-indicator is invalid.
-
Description text
-
Description text
<ul class="list-unstyled">
<li class="switch-item-container">
<div class="switch-item control-item-divider">
<div class="control-item-assets-container">
<input class="control-item-indicator" aria-invalid="true" type="checkbox" role="switch" value="" id="switchItemInvalidUl" aria-describedby="switchItemInvalidUlDescription switchItemInvalidErrorTextUl" checked />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemInvalidUl">Default invalid switch item</label>
<p class="control-item-description" id="switchItemInvalidUlDescription">Description text</p>
</div>
</div>
<p class="control-item-error-message mb-xsmall" id="switchItemInvalidErrorTextUl">Cannot be activated at this time.</p>
</li>
<li class="switch-item-container">
<div class="switch-item control-item-divider">
<div class="control-item-assets-container">
<input class="control-item-indicator" type="checkbox" role="switch" value="" id="switchItemInvalidUl2" aria-describedby="switchItemInvalidUl2Description switchItemInvalidErrorTextUl2" checked />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemInvalidUl2">Default invalid switch item</label>
<p class="control-item-description" id="switchItemInvalidUl2Description">Description text</p>
</div>
</div>
<p class="control-item-error-message" id="switchItemInvalidErrorTextUl2">Cannot be activated at this time.</p>
</li>
</ul>
Error text on a group
If the switch items list is part of a form, add a <fieldset> with the class .control-items-list, the error text will be automatically displayed if any of the .control-item-indicators inside the <fieldset> is invalid.
<fieldset class="control-items-list">
<div class="switch-item">
<div class="control-item-assets-container">
<input class="control-item-indicator" aria-invalid="true" type="checkbox" role="switch" value="" id="switchItemInvalidFieldset" aria-describedby="switchItemInvalidFieldsetDescription switchItemInvalidErrorTextGroup" />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemInvalidFieldset">Default invalid switch item</label>
<p class="control-item-description" id="switchItemInvalidFieldsetDescription">Description text</p>
</div>
</div>
<div class="switch-item">
<div class="control-item-assets-container">
<input class="control-item-indicator" aria-invalid="true" type="checkbox" role="switch" value="" id="switchItemInvalidFieldset2" aria-describedby="switchItemInvalidFieldset2Description switchItemInvalidErrorTextGroup" checked />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemInvalidFieldset2">Checked invalid switch item</label>
<p class="control-item-description" id="switchItemInvalidFieldset2Description">Description text</p>
</div>
</div>
<p class="control-item-error-message" id="switchItemInvalidErrorTextGroup">Incompatible choices.</p>
</fieldset>
Skeleton
To set the switch item in skeleton state, it needs to be wrapped in an [aria-busy="true"] container that also has the inert attribute. To get more information, please refer to the skeleton documentation.
<div aria-busy="true" inert>
<div class="switch-item">
<div class="control-item-assets-container">
<input class="control-item-indicator" type="checkbox" role="switch" value="" id="switchItemSkeleton" />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemSkeleton">Skeleton switch item</label>
</div>
</div>
</div>
Layout
Default
It's recommended to keep switch item label to no more than three words. When space is limited or when a long label or description text is required, the text can wrap, as this is preferable to truncation. The switch indicator and the icon will remain vertically centered, until the .control-item-assets-container reaches a defined maximum height.
-
Description text
-
Also a longer description text, it will also wrap at some point depending on the component width
<div class="row">
<div class="col-8 md:col-6 xl:col-5">
<ul class="control-items-list">
<li class="switch-item control-item-divider">
<div class="control-item-assets-container">
<input class="control-item-indicator" type="checkbox" role="switch" value="" id="switchItemLayout1" aria-describedby="switchItemLayout1Description" />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemLayout1">Label</label>
<p class="control-item-description" id="switchItemLayout1Description">Description text</p>
</div>
<div class="control-item-assets-container">
<svg aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#heart-empty" />
</svg>
</div>
</li>
<li class="switch-item control-item-divider">
<div class="control-item-assets-container">
<input class="control-item-indicator" type="checkbox" role="switch" value="" id="switchItemLayout2" checked aria-describedby="switchItemLayout2Description" />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemLayout2">A longer label for showing behavior in this case, the switch indicator and icon will stick to the top area of the component</label>
<p class="control-item-description" id="switchItemLayout2Description">Also a longer description text, it will also wrap at some point depending on the component width</p>
</div>
<div class="control-item-assets-container">
<svg aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#heart-empty" />
</svg>
</div>
</li>
</ul>
</div>
</div>
Reverse
To reverse the switch item, simply add .control-item-reverse to a .switch-item.
-
Description text
-
Also a longer description text, it will also wrap at some point depending on the component width
<div class="row">
<div class="col-8 md:col-6 xl:col-5">
<ul class="control-items-list">
<li class="switch-item control-item-divider control-item-reverse">
<div class="control-item-assets-container">
<input class="control-item-indicator" type="checkbox" role="switch" value="" id="switchItemLayoutRev1" aria-describedby="switchItemLayoutRev1Description" />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemLayoutRev1">Label with reverse layout</label>
<p class="control-item-description" id="switchItemLayoutRev1Description">Description text</p>
</div>
<div class="control-item-assets-container">
<svg aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#heart-empty" />
</svg>
</div>
</li>
<li class="switch-item control-item-divider control-item-reverse">
<div class="control-item-assets-container">
<input class="control-item-indicator" type="checkbox" role="switch" value="" id="switchItemLayoutRev2" checked aria-describedby="switchItemLayoutRev2Description" />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemLayoutRev2">A longer label with reverse layout for showing behavior in this case, the switch indicator and icon will stick to the top area of the component</label>
<p class="control-item-description" id="switchItemLayoutRev2Description">Also a longer description text, it will also wrap at some point depending on the component width</p>
</div>
<div class="control-item-assets-container">
<svg aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#heart-empty" />
</svg>
</div>
</li>
</ul>
</div>
</div>
Bootstrap
$enable-bootstrap-compatibility: true
Put your switch items on the opposite side with the .form-check-reverse modifier class.
<div class="form-check form-switch form-check-reverse">
<input class="form-check-input" type="checkbox" role="switch" id="switchItemCheckReverse" checked />
<label class="form-check-label" for="switchItemCheckReverse">Reverse switch item (Bootstrap compatible)</label>
</div>
Max width
By default, switch items will span the whole width of their parent container, to limit the width of the switch item on wider parent container, add a .component-max-width to the .switch-item container. More information on switch item sizing in the design guidelines.
<div class="switch-item component-max-width">
<div class="control-item-assets-container">
<input class="control-item-indicator" type="checkbox" role="switch" value="" id="switchItemMaxWidth" checked />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemMaxWidth">Checked switch item with max width</label>
</div>
<div class="control-item-assets-container">
<span class="icon si si-settings" aria-hidden="true"></span>
</div>
</div>
Fieldset <legend>
For accessibility reasons, it is required to provide understandable switch item labels without relying on visual context. If switch items belong to a group, it is good practice to add a group title inside a <legend> element as the first child of the <fieldset> element. Screen readers will read the legend before navigating through the switch items; this way, keyboard navigation users have more information on what is expected with the multiple switch items element.
<div class="row">
<div class="md:col-6">
<fieldset class="control-items-list">
<legend>Switch items group example</legend>
<div class="switch-item control-item-divider">
<div class="control-item-assets-container">
<input class="control-item-indicator" type="checkbox" role="switch" value="" id="switchItemGroup1" aria-describedby="switchItemGroup1Description" />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemGroup1">Switch item 1</label>
<p class="control-item-description" id="switchItemGroup1Description">Description text</p>
</div>
<div class="control-item-assets-container">
<svg aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#heart-empty" />
</svg>
</div>
</div>
<div class="switch-item control-item-divider">
<div class="control-item-assets-container">
<input class="control-item-indicator" type="checkbox" role="switch" value="" id="switchItemGroup2" checked aria-describedby="switchItemGroup2Description" />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchItemGroup2">Switch item 2</label>
<p class="control-item-description" id="switchItemGroup2Description">Description text</p>
</div>
<div class="control-item-assets-container">
<svg aria-hidden="true">
<use xlink:href="/sosh/docs/1.6/assets/img/ouds-web-sprite.svg#heart-empty" />
</svg>
</div>
</div>
</fieldset>
</div>
</div>
Mandatory field indication
To indicate that a switch item is mandatory in a form, add the class .is-required to display a red asterisk at the end of the label.
For general rules about when to add mandatory fields indication, please refer to the switch item design guidelines and to the form validation documentation. In particular, do not forget to handle error messages.
<div class="switch-item-container">
<div class="switch-item component-max-width">
<div class="control-item-assets-container">
<input class="control-item-indicator" type="checkbox" role="switch" value="" id="switchItemUniqueMandatory" name="mandatorySwitchItem" required />
</div>
<div class="control-item-text-container">
<label class="control-item-label is-required" for="switchItemUniqueMandatory">Mandatory unique switch item</label>
</div>
</div>
</div>
<hr class="my-xlarge">
<fieldset class="control-items-list">
<legend class="is-required">Mandatory switch items</legend>
<div class="switch-item component-max-width">
<div class="control-item-assets-container">
<input class="control-item-indicator" type="checkbox" role="switch" value="" id="mandatorySwitchItem1" name="mandatorySwitchItems" required />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="mandatorySwitchItem1">Default switch item</label>
</div>
</div>
<div class="switch-item component-max-width">
<div class="control-item-assets-container">
<input checked class="control-item-indicator" type="checkbox" role="switch" value="" id="mandatorySwitchItem2" name="mandatorySwitchItems" required />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="mandatorySwitchItem2">Checked switch item</label>
</div>
</div>
</fieldset>
Switch
Switch is a UI element that toggles between two states, typically "On" and "Off," and is used to enable or disable features, options, or settings.
Switch, that lacks an additional icon asset or text label, provides greater flexibility when creating other components that require a switch.
For the standalone switch, we provide a completely different architecture than switch item to ease the integration inside your projects.
<label class="switch-standalone">
<input class="control-item-indicator" type="checkbox" role="switch" value="" />
<span class="visually-hidden">Switch</span>
</label>
States
Disabled
Add the disabled attribute to prevent interaction with the switch and remove it from the keyboard tab order.
<label class="switch-standalone">
<input disabled class="control-item-indicator" type="checkbox" role="switch" value="" />
<span class="visually-hidden">Disabled switch</span>
</label>
Read only
Switch inputs do not support the readonly attribute. Replace the input with an element that has role="switch", aria-readonly="true", aria-disabled="true", aria-checked, and tabindex="0".
<span class="switch-standalone">
<span class="control-item-indicator" role="switch" aria-readonly="true" aria-disabled="true" tabindex="0" aria-checked="true" aria-label="Read only switch"></span>
</span>
Invalid
To manually mark a switch as invalid, add aria-invalid="true" to the input and use aria-describedby to associate an error message with it.
This setting cannot be enabled.
<div>
<label class="switch-standalone">
<input class="control-item-indicator" type="checkbox" role="switch" value="" aria-invalid="true" aria-describedby="switchStandaloneError" />
<span class="visually-hidden">Switch</span>
</label>
<p id="switchStandaloneError">This setting cannot be enabled.</p>
</div>
Native switches
Progressively enhance your switches for mobile Safari (iOS 17.4+) by adding a switch attribute to your input to enable haptic feedback when toggling switches, just like native iOS switches. There are no style changes attached to using this attribute in OUDS Web as all our switches use custom styles.
<div class="switch-item">
<div class="control-item-assets-container">
<input class="control-item-indicator" type="checkbox" role="switch" value="" id="switchNative" switch />
</div>
<div class="control-item-text-container">
<label class="control-item-label" for="switchNative">Native switch haptics</label>
</div>
</div>
Be sure to read more about the switch attribute on the WebKit blog. Safari 17.4+ on macOS and iOS both have native-style switches in HTML while other browsers simply fall back to the standard checkbox appearance. Applying the attribute to a non-OUDS Web checkbox in more recent versions of Safari will render a native switch.