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

Shareholder view 
<sl-switch>Shareholder view</sl-switch>

sl-switch Shareholder view

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

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

Label Position

Use the label-position attribute to change the position of the switch’s label. The default position is right.

Shareholder view President view Admin view 
<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.

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. Size medium is the switch’s default.

Small switch
Medium switch (default) 
<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.

Shareholder view Admin view Please avoid doing this 
<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.

Large custom switch 
<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

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 checked state

Component Props

Property Default Details
name ''

string

The name of the switch, submitted as a name/value pair with form data.
value —

string

The current value of the switch, submitted as a name/value pair with form data.
labelPosition
label-position 		'right'

'right' | 'left' | 'left-justified'

The switch’s label position.
size 'medium'

'small' | 'medium' | 'large'

The switch’s size.
disabled false

boolean

Disables the switch.
checked false

boolean

Draws the switch in a checked state.
defaultChecked false

boolean

The default value of the form control. Primarily used for resetting the form control.
form ''

string

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.

required false

boolean

Makes the switch a required field.
helpText
help-text 		''

string

The switch’s help text. If you need to display HTML, use the help-text slot instead.

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.

Slots

Name Details
(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.

Events

Name Name React Event Details
sl-blur sl-blur onSlBlur

Emitted when the control loses focus.
sl-change sl-change onSlChange

Emitted when the control’s checked state changes.
sl-input sl-input onSlInput

Emitted when the control receives input.
sl-focus sl-focus onSlFocus

Emitted when the control gains focus.
sl-invalid 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 Details
click()

Simulates a click on the switch.
focus()

options: FocusOptions

Sets focus on the switch.
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()

message: string

Sets a custom validation message. Pass an empty string to restore validity.

Learn more about methods.

Custom Properties

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

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