Toggle Switch

A choice between two mutually exclusive options.

styleKey: toggleSwitch

scriptKey: toggleSwitch

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>

Disabled

Use disabled when the toggle option is permanently set or is dependent on a prior user action. Use a message to explain why the option cannot be toggled.

ReactVanilla

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

<Box>
  <Span visuallyHidden id="label-example">
    Toggle switch example
  </Span>
  <ToggleSwitch disabled 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>

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

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

prop	type	required	default	deprecation notes
`aria-label` Defines a string value that labels the current element. Provides a localized accessible label which describes what the Toggle Switch's purpose is. Prefer `aria-labelledby` over this and use it when you don't have access to the `id` of the labeling element. This is separate from the ToggleSwitchOnLabel/ToggleSwitchOffLabel and cannot change based on the switch state. e.g. "Include VAT" @see aria-labelledby.	`string`	false	null
`aria-labelledby` Identifies the element (or elements) that labels the current element. ID of an element whose text content labels the Toggle Switch. The referenced element's text should be localized. e.g. id of element with text "Include VAT" @see aria-describedby.	`string`	false	null
⚠️ Deprecated `size` Size (height) of the toggle. @deprecated This is deprecated without a replacement.	`"standard""mini""super"null`	false	standard	This is deprecated without a replacement.
`hideText` Whether the on/off text is visually hidden	`booleannull`	false	false
`activated` Whether or not the switch is "activated" aka "on"	`booleannull`	false	null
`onRequestActivatedChange` Callback fired when the ToggleSwitch wants to change its activated state	`((activated: boolean, event: MouseEvent<HTMLButtonElement, MouseEvent>) => void)null`	false	null
`defaultActivated` The initial activated state. Ignored if `activated` is provided	`booleannull`	false	false

Toggle Switch

Use Toggle Switch...

Don't use Toggle Switch...

Size

Hide Text

Disabled

Managing state

Accessibility

Content

References

Props

Related