ToggleSwitch

ToggleSwitch is used to immediately toggle a setting on or off.

Page navigation navigation

React

readyNot reviewed for a11y

Storybook|Source

Rails

readyNot reviewed for a11y

Docs|Lookbook|Source

Figma

View in Figma|

React examples

Default

Label

<Stack direction="horizontal" align="center">
  <div id="default-toggle-label">Label</div>
  <ToggleSwitch aria-labelledby="default-toggle-label" />
</Stack>

<Stack direction="horizontal" align="center">
  <div id="default-toggle-label">Label</div>
  <ToggleSwitch aria-labelledby="default-toggle-label" />
</Stack>

With a caption

Label

Switch caption

<Stack gap="none">
  <Stack direction="horizontal" align="center" gap="spacious">
    <Text id="captioned-toggle-label" sx={{display: 'block', fontWeight: 'var(--base-text-weight-semibold)'}}>
      Label
    </Text>
    <ToggleSwitch aria-labelledby="captioned-toggle-label" aria-describedby="captioned-toggle-caption" />
  </Stack>
  <Text
    id="captioned-toggle-caption"
    sx={{color: 'var(--fgColor-muted)', display: 'block', fontSize: 'var(--text-body-size-small)'}}
  >
    Switch caption
  </Text>
</Stack>

<Stack gap="none">
  <Stack direction="horizontal" align="center" gap="spacious">
    <Text id="captioned-toggle-label" sx={{display: 'block', fontWeight: 'var(--base-text-weight-semibold)'}}>
      Label
    </Text>
    <ToggleSwitch aria-labelledby="captioned-toggle-label" aria-describedby="captioned-toggle-caption" />
  </Stack>
  <Text
    id="captioned-toggle-caption"
    sx={{color: 'var(--fgColor-muted)', display: 'block', fontSize: 'var(--text-body-size-small)'}}
  >
    Switch caption
  </Text>
</Stack>

Custom size

A small toggle variant is available for dense layouts.

Default

Small

<Stack>
  <Stack direction="horizontal" align="center">
    <div id="size-toggle-label">Default</div>
    <ToggleSwitch aria-labelledby="size-toggle-label" />
  </Stack>
  <Stack direction="horizontal" align="center">
    <div id="size-toggle-label-small">Small</div>
    <ToggleSwitch size="small" aria-labelledby="size-toggle-label-small" />
  </Stack>
</Stack>

<Stack>
  <Stack direction="horizontal" align="center">
    <div id="size-toggle-label">Default</div>
    <ToggleSwitch aria-labelledby="size-toggle-label" />
  </Stack>
  <Stack direction="horizontal" align="center">
    <div id="size-toggle-label-small">Small</div>
    <ToggleSwitch size="small" aria-labelledby="size-toggle-label-small" />
  </Stack>
</Stack>

Status label after switch

Label

<Stack direction="horizontal" align="center">
  <div id="statusAfterSwitch-toggle-label">Label</div>
  <ToggleSwitch statusLabelPosition="end" aria-labelledby="statusAfterSwitch-toggle-label" />
</Stack>

<Stack direction="horizontal" align="center">
  <div id="statusAfterSwitch-toggle-label">Label</div>
  <ToggleSwitch statusLabelPosition="end" aria-labelledby="statusAfterSwitch-toggle-label" />
</Stack>

In a loading state

Display a loading indicator when waiting for an action to complete before toggling.

Label

<Stack direction="horizontal" align="center">
  <div id="loading-toggle-label">Label</div>
  <ToggleSwitch loading aria-labelledby="loading-toggle-label" />
</Stack>

<Stack direction="horizontal" align="center">
  <div id="loading-toggle-label">Label</div>
  <ToggleSwitch loading aria-labelledby="loading-toggle-label" />
</Stack>

Props

ToggleSwitch

Name	Default	Description
aria-describedby		`string` The id of the DOM node that describes the switch
aria-labelledby Required		`string` The id of the DOM node that labels the switch
defaultChecked		`boolean` Uncontrolled - whether the switch is turned on
disabled		`boolean` Whether the switch is ready for user input
loading		`boolean` Whether the switch's value is being calculated
checked		`boolean` Whether the switch is turned on
onChange		`(on: boolean) => void` The callback that is called when the switch is toggled on or off
onClick		`(e: MouseEvent) => void` The callback that is called when the switch is clicked
size	`'medium'`	`'small' \| 'medium'` Size of the switch
statusLabelPosition	`'start'`	`'start' \| 'end'` Whether the "on" and "off" labels should appear before or after the switch. This should only be changed when the switch's alignment needs to be adjusted. For example: It needs to be left-aligned because the label appears above it and the caption appears below it.