Toggle Switch

A choice between two mutually exclusive options.

scriptKeys: toggleSwitchstyleKeys: toggleSwitch

Some props/prop values deprecated in SWAN v3.3
Refer to the information on props/prop values provided further down this page. Find more information and migration documentation in the Deprecation roadmap.

UsageGuidelinesAPI

Use Toggle Switch...

To prompt users to choose between two mutually exclusive options that always have a default value, like "on" or "off".
When immediately activating or deactivating the selected choice or setting.

Don't use Toggle Switch...

If you need to display an indeterminate value. A Toggle Switch is either "on" or "off". Use Checkbox instead.
To select more than one option. Use Checkbox instead.
To apply a setting that needs to be confirmed and reviewed by the user before they are submitted. Use Checkbox instead.
To select one option from a list of options. Use Radio Button instead.

ReactVanilla

<Box>
  <Span visuallyHidden id="label-example">
    Toggle switch example
  </Span>
  <ToggleSwitch defaultActivated aria-labelledby="label-example">
    <ToggleSwitchOnLabel>On</ToggleSwitchOnLabel>
    <ToggleSwitchOffLabel>Off</ToggleSwitchOffLabel>
  </ToggleSwitch>
</Box>

<Box>
  <Span visuallyHidden id="label-example">
    Toggle switch example
  </Span>
  <ToggleSwitch defaultActivated aria-labelledby="label-example">
    <ToggleSwitchOnLabel>On</ToggleSwitchOnLabel>
    <ToggleSwitchOffLabel>Off</ToggleSwitchOffLabel>
  </ToggleSwitch>
</Box>

<div>
  <span id="label-example" class="swan-visually-hidden">
    Toggle switch example
  </span>
  <button
    aria-labelledby="label-example"
    role="switch"
    aria-checked="true"
    class="swan-toggle-switch"
  >
    <span class="swan-toggle-switch-text-on">On</span>
    <span class="swan-toggle-switch-text-off">Off</span>
  </button>
</div>

<div>
  <span id="label-example" class="swan-visually-hidden">
    Toggle switch example
  </span>
  <button
    aria-labelledby="label-example"
    role="switch"
    aria-checked="true"
    class="swan-toggle-switch"
  >
    <span class="swan-toggle-switch-text-on">On</span>
    <span class="swan-toggle-switch-text-off">Off</span>
  </button>
</div>

Size

size is deprecated in SWAN v3.3

The component now automatically handles sizing based on the selected mode(standardMode/compactMode). Please update your implementation to rely on the new mode-based sizing.

Use size="mini" to reduce the height of a Toggle.

ReactVanilla

<Box>
  <Span visuallyHidden id="mini-label-example">
    Mini toggle switch example
  </Span>
  <ToggleSwitch
    defaultActivated
    size="mini"
    aria-labelledby="mini-label-example"
  >
    <ToggleSwitchOnLabel>On</ToggleSwitchOnLabel>
    <ToggleSwitchOffLabel>Off</ToggleSwitchOffLabel>
  </ToggleSwitch>
</Box>

<Box>
  <Span visuallyHidden id="mini-label-example">
    Mini toggle switch example
  </Span>
  <ToggleSwitch
    defaultActivated
    size="mini"
    aria-labelledby="mini-label-example"
  >
    <ToggleSwitchOnLabel>On</ToggleSwitchOnLabel>
    <ToggleSwitchOffLabel>Off</ToggleSwitchOffLabel>
  </ToggleSwitch>
</Box>

<div>
  <span id="mini-label-example" class="swan-visually-hidden">
    Mini toggle switch example
  </span>
  <button
    aria-labelledby="mini-label-example"
    role="switch"
    aria-checked="true"
    class="swan-toggle-switch swan-toggle-switch-mini"
  >
    <span class="swan-toggle-switch-text-on">On</span>
    <span class="swan-toggle-switch-text-off">Off</span>
  </button>
</div>

<div>
  <span id="mini-label-example" class="swan-visually-hidden">
    Mini toggle switch example
  </span>
  <button
    aria-labelledby="mini-label-example"
    role="switch"
    aria-checked="true"
    class="swan-toggle-switch swan-toggle-switch-mini"
  >
    <span class="swan-toggle-switch-text-on">On</span>
    <span class="swan-toggle-switch-text-off">Off</span>
  </button>
</div>

Use size="super" to increase the height of a Toggle.

ReactVanilla

<Box>
  <Span visuallyHidden id="super-label-example">
    Super toggle switch example
  </Span>
  <ToggleSwitch
    defaultActivated
    size="super"
    aria-labelledby="super-label-example"
  >
    <ToggleSwitchOnLabel>On</ToggleSwitchOnLabel>
    <ToggleSwitchOffLabel>Off</ToggleSwitchOffLabel>
  </ToggleSwitch>
</Box>

<Box>
  <Span visuallyHidden id="super-label-example">
    Super toggle switch example
  </Span>
  <ToggleSwitch
    defaultActivated
    size="super"
    aria-labelledby="super-label-example"
  >
    <ToggleSwitchOnLabel>On</ToggleSwitchOnLabel>
    <ToggleSwitchOffLabel>Off</ToggleSwitchOffLabel>
  </ToggleSwitch>
</Box>

<div>
  <span id="super-label-example" class="swan-visually-hidden">
    Super toggle switch example
  </span>
  <button
    aria-labelledby="super-label-example"
    role="switch"
    aria-checked="true"
    class="swan-toggle-switch swan-toggle-switch-super"
  >
    <span class="swan-toggle-switch-text-on">On</span>
    <span class="swan-toggle-switch-text-off">Off</span>
  </button>
</div>

<div>
  <span id="super-label-example" class="swan-visually-hidden">
    Super toggle switch example
  </span>
  <button
    aria-labelledby="super-label-example"
    role="switch"
    aria-checked="true"
    class="swan-toggle-switch swan-toggle-switch-super"
  >
    <span class="swan-toggle-switch-text-on">On</span>
    <span class="swan-toggle-switch-text-off">Off</span>
  </button>
</div>

Hide Text

Use hideText to hide the “On” and “Off” text.

For accessibility support, you are still required to supply both the ToggleSwitchOnLabel and ToggleSwitchOffLabel text. Enabling this option will keep the text accessible to assistive technologies while hiding it only on screens.

ReactVanilla

<Box>
  <Span visuallyHidden id="hidden-label-example">
    Hidden text toggle switch example
  </Span>
  <ToggleSwitch
    hideText
    defaultActivated
    aria-labelledby="hidden-label-example"
  >
    <ToggleSwitchOnLabel>On</ToggleSwitchOnLabel>
    <ToggleSwitchOffLabel>Off</ToggleSwitchOffLabel>
  </ToggleSwitch>
</Box>

<Box>
  <Span visuallyHidden id="hidden-label-example">
    Hidden text toggle switch example
  </Span>
  <ToggleSwitch
    hideText
    defaultActivated
    aria-labelledby="hidden-label-example"
  >
    <ToggleSwitchOnLabel>On</ToggleSwitchOnLabel>
    <ToggleSwitchOffLabel>Off</ToggleSwitchOffLabel>
  </ToggleSwitch>
</Box>

<div>
  <span id="hidden-label-example" class="swan-visually-hidden">
    Hidden text toggle switch example
  </span>
  <button
    aria-labelledby="hidden-label-example"
    role="switch"
    aria-checked="true"
    class="swan-toggle-switch swan-toggle-switch-hide-text"
  >
    <span class="swan-toggle-switch-text-on">On</span>
    <span class="swan-toggle-switch-text-off">Off</span>
  </button>
</div>

<div>
  <span id="hidden-label-example" class="swan-visually-hidden">
    Hidden text toggle switch example
  </span>
  <button
    aria-labelledby="hidden-label-example"
    role="switch"
    aria-checked="true"
    class="swan-toggle-switch swan-toggle-switch-hide-text"
  >
    <span class="swan-toggle-switch-text-on">On</span>
    <span class="swan-toggle-switch-text-off">Off</span>
  </button>
</div>

Managing state

Pass the defaultActivated prop in order to set the initial state.

If you need to keep track of the state for the ToggleSwitch, use the activated and onRequestActivatedChange props.

onRequestActivatedChange will be triggered with the requested activation state as the first arg and the actual event that triggered the change as the second arg in case you need it.

() => {
  const [activated, setActivated] = React.useState(true)
  return (
    <FlexBox flexDirection="column" gap={4}>
      <Span>
        <Span fontSkin="body-standard-bold">Example state:</Span>{' '}
        {activated ? 'On' : 'Off'}{' '}
      </Span>
      <Span visuallyHidden id="state-label-example">
        Managed state toggle switch example
      </Span>
      <Box>
        <ToggleSwitch
          defaultActivated
          activated={activated}
          onRequestActivatedChange={newValue => setActivated(newValue)}
          aria-labelledby="state-label-example"
        >
          <ToggleSwitchOnLabel>On</ToggleSwitchOnLabel>
          <ToggleSwitchOffLabel>Off</ToggleSwitchOffLabel>
        </ToggleSwitch>
      </Box>
    </FlexBox>
  )
}

() => {
  const [activated, setActivated] = React.useState(true)
  return (
    <FlexBox flexDirection="column" gap={4}>
      <Span>
        <Span fontSkin="body-standard-bold">Example state:</Span>{' '}
        {activated ? 'On' : 'Off'}{' '}
      </Span>
      <Span visuallyHidden id="state-label-example">
        Managed state toggle switch example
      </Span>
      <Box>
        <ToggleSwitch
          defaultActivated
          activated={activated}
          onRequestActivatedChange={newValue => setActivated(newValue)}
          aria-labelledby="state-label-example"
        >
          <ToggleSwitchOnLabel>On</ToggleSwitchOnLabel>
          <ToggleSwitchOffLabel>Off</ToggleSwitchOffLabel>
        </ToggleSwitch>
      </Box>
    </FlexBox>
  )
}

Accessibility

The ToggleSwitch component needs an accessible name that describes what the switch controls. The name will be applied to its underlying button element and used by assistive technologies to describe it to its users. This is separate from the ToggleSwitchOnLabel/ToggleSwitchOffLabel and cannot change based on the switch state.

If visible text already exists that summarizes its purpose, update the ToggleSwitch component with an aria-labelledby attribute whose value is the id of the element containing that text.

If no visible text exists that summarizes its purpose, create a visually hidden element with descriptive text, then use aria-labelledby accordingly.

If you don't have access to the id on the labelling element, update the ToggleSwitch component with an aria-label attribute whose value is that descriptive text.

Remember that all text (visible or hidden) must be localized since it will be read to the user!

ReactVanilla

<FlexBox flexDirection="column" gap={8}>
  {/* Example of a visible label + on/off label */}
  <FlexBox flexDirection="column" gap={4}>
    <Typography fontSkin="title-subsection">
      Example of a visible label + on/off label
    </Typography>
    <FlexBox gap="to-actions">
      <span id="label-example-1">Include taxes/fees</span>
      <ToggleSwitch aria-labelledby="label-example-1">
        <ToggleSwitchOnLabel>On</ToggleSwitchOnLabel>
        <ToggleSwitchOffLabel>Off</ToggleSwitchOffLabel>
      </ToggleSwitch>
    </FlexBox>
  </FlexBox>

  {/* Example of on/off label only */}
  <FlexBox flexDirection="column" gap={4}>
    <Typography fontSkin="title-subsection">
      Example of on/off label only
    </Typography>
    <FlexBox gap="to-actions">
      <Span visuallyHidden id="label-example-2">
        Include taxes/fees
      </Span>
      <ToggleSwitch aria-labelledby="label-example-2">
        <ToggleSwitchOnLabel>Exclude taxes/fees</ToggleSwitchOnLabel>
        <ToggleSwitchOffLabel>Include taxes/fees</ToggleSwitchOffLabel>
      </ToggleSwitch>
    </FlexBox>
  </FlexBox>

  {/* Example of visible label only */}
  <FlexBox flexDirection="column" gap={4}>
    <Typography fontSkin="title-subsection">
      Example of visible label only
    </Typography>
    <FlexBox gap="to-actions">
      <Span id="label-example-3">Include taxes/fees</Span>
      <ToggleSwitch hideText aria-labelledby="label-example-3">
        <ToggleSwitchOnLabel>On</ToggleSwitchOnLabel>
        <ToggleSwitchOffLabel>Off</ToggleSwitchOffLabel>
      </ToggleSwitch>
    </FlexBox>
  </FlexBox>

  {/* Example of on/off label + aria-label (not recommended) */}
  <FlexBox flexDirection="column" gap={4}>
    <Typography fontSkin="title-subsection">
      Example of on/off label + aria-label*
    </Typography>
    <Typography fontSkin="footnote">
      *Not recommended, only use when the labelling element's ID is not
      available
    </Typography>
    <FlexBox gap="to-actions">
      <ToggleSwitch aria-label="Include taxes/fees">
        <ToggleSwitchOnLabel>On</ToggleSwitchOnLabel>
        <ToggleSwitchOffLabel>Off</ToggleSwitchOffLabel>
      </ToggleSwitch>
    </FlexBox>
  </FlexBox>
</FlexBox>

<FlexBox flexDirection="column" gap={8}>
  {/* Example of a visible label + on/off label */}
  <FlexBox flexDirection="column" gap={4}>
    <Typography fontSkin="title-subsection">
      Example of a visible label + on/off label
    </Typography>
    <FlexBox gap="to-actions">
      <span id="label-example-1">Include taxes/fees</span>
      <ToggleSwitch aria-labelledby="label-example-1">
        <ToggleSwitchOnLabel>On</ToggleSwitchOnLabel>
        <ToggleSwitchOffLabel>Off</ToggleSwitchOffLabel>
      </ToggleSwitch>
    </FlexBox>
  </FlexBox>

  {/* Example of on/off label only */}
  <FlexBox flexDirection="column" gap={4}>
    <Typography fontSkin="title-subsection">
      Example of on/off label only
    </Typography>
    <FlexBox gap="to-actions">
      <Span visuallyHidden id="label-example-2">
        Include taxes/fees
      </Span>
      <ToggleSwitch aria-labelledby="label-example-2">
        <ToggleSwitchOnLabel>Exclude taxes/fees</ToggleSwitchOnLabel>
        <ToggleSwitchOffLabel>Include taxes/fees</ToggleSwitchOffLabel>
      </ToggleSwitch>
    </FlexBox>
  </FlexBox>

  {/* Example of visible label only */}
  <FlexBox flexDirection="column" gap={4}>
    <Typography fontSkin="title-subsection">
      Example of visible label only
    </Typography>
    <FlexBox gap="to-actions">
      <Span id="label-example-3">Include taxes/fees</Span>
      <ToggleSwitch hideText aria-labelledby="label-example-3">
        <ToggleSwitchOnLabel>On</ToggleSwitchOnLabel>
        <ToggleSwitchOffLabel>Off</ToggleSwitchOffLabel>
      </ToggleSwitch>
    </FlexBox>
  </FlexBox>

  {/* Example of on/off label + aria-label (not recommended) */}
  <FlexBox flexDirection="column" gap={4}>
    <Typography fontSkin="title-subsection">
      Example of on/off label + aria-label*
    </Typography>
    <Typography fontSkin="footnote">
      *Not recommended, only use when the labelling element's ID is not
      available
    </Typography>
    <FlexBox gap="to-actions">
      <ToggleSwitch aria-label="Include taxes/fees">
        <ToggleSwitchOnLabel>On</ToggleSwitchOnLabel>
        <ToggleSwitchOffLabel>Off</ToggleSwitchOffLabel>
      </ToggleSwitch>
    </FlexBox>
  </FlexBox>
</FlexBox>

<div
  class="swan-display-flex"
  style="flex-direction: column; gap: var(--swan-sem-space-8);"
>
  <div
    class="swan-display-flex"
    style="flex-direction: column; gap: var(--swan-sem-space-4);"
  >
    <div class="swan-font-skin-title-subsection">
      Example of a visible label + on/off label
    </div>
    <div
      class="swan-display-flex"
      style="gap: var(--swan-sem-space-to-actions);"
    >
      <span id="label-example-1">Include taxes/fees</span
      ><button
        aria-labelledby="label-example-1"
        role="switch"
        aria-checked="false"
        class="swan-toggle-switch"
      >
        <span class="swan-toggle-switch-text-on">On</span
        ><span class="swan-toggle-switch-text-off">Off</span>
      </button>
    </div>
  </div>
  <div
    class="swan-display-flex"
    style="flex-direction: column; gap: var(--swan-sem-space-4);"
  >
    <div class="swan-font-skin-title-subsection">
      Example of on/off label only
    </div>
    <div
      class="swan-display-flex"
      style="gap: var(--swan-sem-space-to-actions);"
    >
      <span id="label-example-2" class="swan-visually-hidden"
        >Include taxes/fees</span
      ><button
        aria-labelledby="label-example-2"
        role="switch"
        aria-checked="false"
        class="swan-toggle-switch"
      >
        <span class="swan-toggle-switch-text-on">Exclude taxes/fees</span
        ><span class="swan-toggle-switch-text-off">Include taxes/fees</span>
      </button>
    </div>
  </div>
  <div
    class="swan-display-flex"
    style="flex-direction: column; gap: var(--swan-sem-space-4);"
  >
    <div class="swan-font-skin-title-subsection">
      Example of visible label only
    </div>
    <div
      class="swan-display-flex"
      style="gap: var(--swan-sem-space-to-actions);"
    >
      <span id="label-example-3" class="">Include taxes/fees</span
      ><button
        aria-labelledby="label-example-3"
        role="switch"
        aria-checked="false"
        class="swan-toggle-switch swan-toggle-switch-hide-text"
      >
        <span class="swan-toggle-switch-text-on">On</span
        ><span class="swan-toggle-switch-text-off">Off</span>
      </button>
    </div>
  </div>
  <div
    class="swan-display-flex"
    style="flex-direction: column; gap: var(--swan-sem-space-4);"
  >
    <div class="swan-font-skin-title-subsection">
      Example of on/off label + aria-label*
    </div>
    <div class="swan-font-skin-footnote">
      *Not recommended, only use when the labelling element's ID is not
      available
    </div>
    <div
      class="swan-display-flex"
      style="gap: var(--swan-sem-space-to-actions);"
    >
      <button
        aria-label="Include taxes/fees"
        role="switch"
        aria-checked="false"
        class="swan-toggle-switch"
      >
        <span class="swan-toggle-switch-text-on">On</span
        ><span class="swan-toggle-switch-text-off">Off</span>
      </button>
    </div>
  </div>
</div>

<div
  class="swan-display-flex"
  style="flex-direction: column; gap: var(--swan-sem-space-8);"
>
  <div
    class="swan-display-flex"
    style="flex-direction: column; gap: var(--swan-sem-space-4);"
  >
    <div class="swan-font-skin-title-subsection">
      Example of a visible label + on/off label
    </div>
    <div
      class="swan-display-flex"
      style="gap: var(--swan-sem-space-to-actions);"
    >
      <span id="label-example-1">Include taxes/fees</span
      ><button
        aria-labelledby="label-example-1"
        role="switch"
        aria-checked="false"
        class="swan-toggle-switch"
      >
        <span class="swan-toggle-switch-text-on">On</span
        ><span class="swan-toggle-switch-text-off">Off</span>
      </button>
    </div>
  </div>
  <div
    class="swan-display-flex"
    style="flex-direction: column; gap: var(--swan-sem-space-4);"
  >
    <div class="swan-font-skin-title-subsection">
      Example of on/off label only
    </div>
    <div
      class="swan-display-flex"
      style="gap: var(--swan-sem-space-to-actions);"
    >
      <span id="label-example-2" class="swan-visually-hidden"
        >Include taxes/fees</span
      ><button
        aria-labelledby="label-example-2"
        role="switch"
        aria-checked="false"
        class="swan-toggle-switch"
      >
        <span class="swan-toggle-switch-text-on">Exclude taxes/fees</span
        ><span class="swan-toggle-switch-text-off">Include taxes/fees</span>
      </button>
    </div>
  </div>
  <div
    class="swan-display-flex"
    style="flex-direction: column; gap: var(--swan-sem-space-4);"
  >
    <div class="swan-font-skin-title-subsection">
      Example of visible label only
    </div>
    <div
      class="swan-display-flex"
      style="gap: var(--swan-sem-space-to-actions);"
    >
      <span id="label-example-3" class="">Include taxes/fees</span
      ><button
        aria-labelledby="label-example-3"
        role="switch"
        aria-checked="false"
        class="swan-toggle-switch swan-toggle-switch-hide-text"
      >
        <span class="swan-toggle-switch-text-on">On</span
        ><span class="swan-toggle-switch-text-off">Off</span>
      </button>
    </div>
  </div>
  <div
    class="swan-display-flex"
    style="flex-direction: column; gap: var(--swan-sem-space-4);"
  >
    <div class="swan-font-skin-title-subsection">
      Example of on/off label + aria-label*
    </div>
    <div class="swan-font-skin-footnote">
      *Not recommended, only use when the labelling element's ID is not
      available
    </div>
    <div
      class="swan-display-flex"
      style="gap: var(--swan-sem-space-to-actions);"
    >
      <button
        aria-label="Include taxes/fees"
        role="switch"
        aria-checked="false"
        class="swan-toggle-switch"
      >
        <span class="swan-toggle-switch-text-on">On</span
        ><span class="swan-toggle-switch-text-off">Off</span>
      </button>
    </div>
  </div>
</div>

Content

Provide concise, explicit labels.
Describe the option that the switch controls.
Provide an explanatory error message.

References

NN/g toggle switch guidelines

Props

ToggleSwitch

This component is implemented using the <button /> as the root element. You can utilize the native attributes supported by <button /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.

See core props for additional props that can be applied to this component.

prop	type	required	description	default
size	`"standard" \| "mini" \| "super" \| null`	false	⚠️ Deprecated - This is deprecated without a replacement. Size (height) of the toggle. Available options: 'standard', 'super', 'mini'	standard
hideText	`boolean \| null`	false	Whether the on/off text is visually hidden	false
activated	`boolean \| null`	false	Whether or not the switch is "activated" aka "on"	null
onRequestActivatedChange	`((activated: boolean, event: MouseEvent<HTMLButtonElement, MouseEvent>) => void) \| null`	false	Callback fired when the ToggleSwitch wants to change its activated state	null
defaultActivated	`boolean \| null`	false	The initial activated state. Ignored if `activated` is provided	false

ToggleSwitchOffLabel

This component is implemented using the <span /> as the root element. You can utilize the native attributes supported by <span /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.

See core props for additional props that can be applied to this component.

ToggleSwitchOnLabel

See core props for additional props that can be applied to this component.

Toggle Switch

Use Toggle Switch...

Don't use Toggle Switch...

Size

Hide Text

Managing state

Accessibility

Content

References

Props

Related