Since Shoelace 2.0 Code stable Pattern stable Figma ready

Switch

<sl-switch> | SlSwitch

Switches allow the user to toggle an option on or off.

Examples

Basic Switch

Switch 
<sl-switch>Switch</sl-switch>

sl-switch Switch

import SlSwitch from '@teamshares/shoelace/dist/react/switch';

const App = () => <SlSwitch>Switch</SlSwitch>;

Checked

Use the checked attribute to activate the switch.

Checked 
<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.

Disabled 
<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.

Small
Medium
Large 
<sl-switch size="small">Small</sl-switch>
<br />
<sl-switch size="medium">Medium</sl-switch>
<br />
<sl-switch size="large">Large</sl-switch>

sl-switch size="small" Small
br
sl-switch size="medium" Medium
br
sl-switch size="large" Large

import SlSwitch from '@teamshares/shoelace/dist/react/switch';

const App = () => (
  <>
    <SlSwitch size="small">Small</SlSwitch>
    <br />
    <SlSwitch size="medium">Medium</SlSwitch>
    <br />
    <SlSwitch size="large">Large</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.

Label 
<sl-switch help-text="What should the user know about the switch?">Label</sl-switch>

sl-switch help-text="What should the user know about the switch?" Label

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.

Really big 
<sl-switch style="--width: 80px; --height: 40px; --thumb-size: 36px;">Really big</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'
    }}
  />
);

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.

Script Import Bundler React

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

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