Switch
<sl-switch> | SlSwitch
Switches allow the user to toggle an option on or off.
Examples
Basic Switch
<sl-switch>Shareholder view</sl-switch>
sl-switch Shareholder view
import SlSwitch from '@teamshares/shoelace/dist/react/switch'; const App = () => <SlSwitch>Switch</SlSwitch>;
This component works with standard <form> elements. Please refer to the section on
form controls to learn more about form submission and
client-side validation.
Label Position
Use the label-position attribute to change the position of the switch’s label. The default
position is right.
<sl-switch>Shareholder view</sl-switch> <sl-divider style="--spacing: 2rem;"></sl-divider> <sl-switch label-position="left">President view</sl-switch> <sl-divider style="--spacing: 2rem;"></sl-divider> <sl-switch label-position="left-justified">Admin view</sl-switch>
sl-switch Shareholder view sl-divider style="--spacing: 2rem;" sl-switch label-position="left" President view sl-divider style="--spacing: 2rem;" sl-switch label-position="left-justified" Shareholder view
import SlSwitch from '@teamshares/shoelace/dist/react/switch'; const App = () => <SlSwitch>Switch</SlSwitch>;
Checked
Use the checked attribute to activate the switch.
<sl-switch checked>Checked</sl-switch>
sl-switch checked="true" Checked
import SlSwitch from '@teamshares/shoelace/dist/react/switch'; const App = () => <SlSwitch checked>Checked</SlSwitch>;
Disabled
Use the disabled attribute to disable the switch.
<sl-switch disabled>Disabled</sl-switch>
sl-switch disabled="true" Disabled
import SlSwitch from '@teamshares/shoelace/dist/react/switch'; const App = () => <SlSwitch disabled>Disabled</SlSwitch>;
Sizes
Use the size attribute to change a switch’s size. Size medium is the switch’s
default.
Size large is currently not part of the Teamshares Design System, and there is no Figma
component for this option. Please check with the design team before using this option.
<sl-switch size="small">Small switch</sl-switch> <br /> <sl-switch size="medium">Medium switch (default)</sl-switch>
sl-switch size="small" Small switch br sl-switch size="medium" Medium switch (default)
import SlSwitch from '@teamshares/shoelace/dist/react/switch'; const App = () => ( <> <SlSwitch size="small">Small</SlSwitch> <br /> <SlSwitch size="medium">Medium</SlSwitch> </> );
Help Text
Add descriptive help text to a switch with the help-text attribute. For help texts that contain
HTML, use the help-text slot instead.
Note: To avoid awkward alignment of the switch, label, and help text, don’t display help
text when using label-position="left".
<sl-switch help-text="Displays company financials">Shareholder view</sl-switch> <sl-divider style="--spacing: 2rem;"></sl-divider> <sl-switch label-position="left-justified" help-text="Displays network financials and reporting data">Admin view</sl-switch> <sl-divider style="--spacing: 2rem;"></sl-divider> <sl-switch label-position="left" help-text="Don't display help text when using label-position: 'left'" checked>Please avoid doing this</sl-switch>
sl-switch help-text="Displays company financials" | Shareholder view sl-divider style="--spacing: 2rem;" sl-switch label-position="left-justified" help-text="Displays network financials and reporting data" | Shareholder view
import SlSwitch from '@shoelace-style/shoelace/dist/react/checkbox'; const App = () => <SlSwitch help-text="What should the user know about the switch?">Label</SlSwitch>;
Custom Styles
Use the available custom properties to change how the switch is styled.
Note: In general, you shouldn’t need to do this. If you are working on a design that requires custom styling, please ensure that there’s not a standard switch in the design system that would work instead. If you really do need a non-standard switch, please consult the design team before implementing a custom version, so that the team can determine whether the existing pattern should be updated.
<sl-switch style="--width: 80px; --height: 40px; --thumb-size: 36px;"><span style="font-size:1.25rem; padding-left: .5rem;">Large custom switch</span></sl-switch>
sl-switch style="--width: 80px; --height: 40px; --thumb-size: 36px;" Really big
import SlSwitch from '@teamshares/shoelace/dist/react/switch'; const App = () => ( <SlSwitch style={{ '--width': '80px', '--height': '32px', '--thumb-size': '26px' }} /> );
Usage Guidelines
Switch or Checkbox?
- Use a switch to let people toggle a setting that takes effect immediately, like a light switch
- Use a checkbox to let people toggle a selection that must be saved before taking effect
Switch Labels
- Always have a label for the switch
- Use sentence case for labels
- Don’t end labels with punctuation
- Keep labels short and easy to scan
- Only use a leading verb if it clarifies the switch’s purpose
- Avoid phrases that describe the switch’s “on” state (e.g. “Turn on” or “Enable”)
-
Don’t update the switch’s label dynamically based on its
checkedstate
Do
- Do use sentence case and keep the label short
- Do use a leading verb if it clarifies what the switch does
Don’t
- Don’t use title case or end with punctuation
- Don’t use negative labels (like “hide” and “disable”) that conflict with the “on” state of the switch
- Don’t repeat the switch’s “on” state in the label
Importing
If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.
To import this component from the CDN using a script tag:
<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.1.0/cdn/components/switch/switch.js"></script>
To import this component from the CDN using a JavaScript import:
import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.1.0/cdn/components/switch/switch.js';
To import this component using a bundler:
import '@shoelace-style/shoelace/dist/components/switch/switch.js';
To import this component as a React component:
import SlSwitch from '@shoelace-style/shoelace/dist/react/switch';
Slots
| Name | Description |
|---|---|
| (default) | The switch’s label. |
help-text
|
Text that describes how to use the switch. Alternatively, you can use the
help-text attribute.
|
Learn more about using slots.
Properties
Note: The following appear as options in the Properties table but are currently not part of the Teamshares Design System. Please check with the design team before using these options:
- Size
large
Scroll right to see the entire table
| Name | Description | Reflects | Type | Default |
|---|---|---|---|---|
name
|
The name of the switch, submitted as a name/value pair with form data. |
string
|
''
|
|
value
|
The current value of the switch, submitted as a name/value pair with form data. |
string
|
- | |
labelPosition
label-position
|
The switch’s label position. |
|
'right' | 'left' | 'left-justified'
|
'right'
|
size
|
The switch’s size. |
|
'small' | 'medium' | 'large'
|
'medium'
|
disabled
|
Disables the switch. |
|
boolean
|
false
|
checked
|
Draws the switch in a checked state. |
|
boolean
|
false
|
defaultChecked
|
The default value of the form control. Primarily used for resetting the form control. |
boolean
|
false
|
|
form
|
By default, form controls are associated with the nearest containing
<form> element. This attribute allows you to place the form control outside of a
form and associate it with the form that has this id. The form must be in the same
document or shadow root for this to work.
|
|
string
|
''
|
required
|
Makes the switch a required field. |
|
boolean
|
false
|
helpText
help-text
|
The switch’s help text. If you need to display HTML, use the help-text slot instead.
|
string
|
''
|
|
validity
|
Gets the validity state object | - | - | |
validationMessage
|
Gets the validation message | - | - | |
updateComplete
|
A read-only promise that resolves when the component has finished updating. |
Learn more about attributes and properties.
Events
| Name | React Event | Description | Event Detail |
|---|---|---|---|
sl-blur
|
onSlBlur
|
Emitted when the control loses focus. | - |
sl-change
|
onSlChange
|
Emitted when the control’s checked state changes. | - |
sl-input
|
onSlInput
|
Emitted when the control receives input. | - |
sl-focus
|
onSlFocus
|
Emitted when the control gains focus. | - |
sl-invalid
|
onSlInvalid
|
Emitted when the form control has been checked for validity and its constraints aren’t satisfied. | - |
Learn more about events.
Methods
| Name | Description | Arguments |
|---|---|---|
click()
|
Simulates a click on the switch. | - |
focus()
|
Sets focus on the switch. |
options: FocusOptions
|
blur()
|
Removes focus from the switch. | - |
checkValidity()
|
Checks for validity but does not show a validation message. Returns true when valid and
false when invalid.
|
- |
getForm()
|
Gets the associated form, if one exists. | - |
reportValidity()
|
Checks for validity and shows the browser’s validation message if the control is invalid. | - |
setCustomValidity()
|
Sets a custom validation message. Pass an empty string to restore validity. |
message: string
|
Learn more about methods.
Custom Properties
| Name | Description | Default |
|---|---|---|
--width
|
The width of the switch. | |
--height
|
The height of the switch. | |
--thumb-size
|
The size of the thumb. |
Learn more about customizing CSS custom properties.
Parts
| Name | Description |
|---|---|
base
|
The component’s base wrapper. |
control
|
The control that houses the switch’s thumb. |
thumb
|
The switch’s thumb. |
label
|
The switch’s label. |
form-control-help-text
|
The help text’s wrapper. |
Learn more about customizing CSS parts.