Toggle Switch

<ToggleSwitch
  defaultActivated
  aria-labelledby="exampleToggleSwitchLabellingElement"
>
  <ToggleSwitchOnLabel>On</ToggleSwitchOnLabel>
  <ToggleSwitchOffLabel>Off</ToggleSwitchOffLabel>
</ToggleSwitch>

<button
  role="switch"
  class="toggle-switch"
  aria-checked="true"
  aria-labelledby="exampleToggleSwitchLabellingElement"
>
  <span class="toggle-switch-text-on">On text</span>
  <span class="toggle-switch-text-off">Off text</span>
</button>

Size

You can adjust the size of the switch to "mini" (smaller) or "super" (larger).

<Box>
  <Box my="2">
    <ToggleSwitch
      defaultActivated
      sizeVariant="mini"
      aria-labelledby="exampleToggleSwitchLabellingElement"
    >
      <ToggleSwitchOnLabel>On</ToggleSwitchOnLabel>
      <ToggleSwitchOffLabel>Off</ToggleSwitchOffLabel>
    </ToggleSwitch>
  </Box>

  <Box my="2">
    <ToggleSwitch
      defaultActivated
      sizeVariant="super"
      aria-labelledby="exampleToggleSwitchLabellingElement"
    >
      <ToggleSwitchOnLabel>On</ToggleSwitchOnLabel>
      <ToggleSwitchOffLabel>Off</ToggleSwitchOffLabel>
    </ToggleSwitch>
  </Box>
</Box>

<button
  role="switch"
  aria-checked="true"
  aria-labelledby="exampleToggleSwitchLabellingElement"
  class="toggle-switch toggle-switch-mini"
>
  <span class="toggle-switch-text-on">On</span>
  <span class="toggle-switch-text-off">Off</span>
</button>

<button
  role="switch"
  aria-checked="true"
  aria-labelledby="exampleToggleSwitchLabellingElement2"
  class="toggle-switch toggle-switch-super"
>
  <span class="toggle-switch-text-on">On</span>
  <span class="toggle-switch-text-off">Off</span>
</button>

Hide Text

You can use the "hide text" option to hide the "on" and "off" text on screens. Note: you must still provide the "on" and "off" text, for accessibility support! Using this option will leave that text available to assistive technologies, hiding the text on screens only.

<ToggleSwitch
  hideText
  defaultActivated
  aria-labelledby="exampleToggleSwitchLabellingElement"
>
  <ToggleSwitchOnLabel>On</ToggleSwitchOnLabel>
  <ToggleSwitchOffLabel>Off</ToggleSwitchOffLabel>
</ToggleSwitch>

<button
  role="switch"
  aria-checked="true"
  aria-labelledby="exampleToggleSwitchLabellingElement"
  class="toggle-switch toggle-switch-hide-text"
>
  <span class="toggle-switch-text-on">On</span>
  <span class="toggle-switch-text-off">Off</span>
</button>

Managing State

In React

In order to set the initial state, you can pass the defaultActivated prop.

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

onRequestActivatedChange will be invoked 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 (
    <ToggleSwitch
      activated={activated}
      onRequestActivatedChange={() => setActivated()}
    >
      <ToggleSwitchOnLabel>ON</ToggleSwitchOnLabel>
      <ToggleSwitchOffLabel>OFF</ToggleSwitchOffLabel>
    </ToggleSwitch>
  )
}

Components

Guidelines

Don't

• Use a Toggle Switch to toggle between two states that aren't semantically "on" and "off". Instead, consider a  Buttonbar or other treatment.

Developer Guidelines

• The Toggle Switch must have an aria-labelledby attribute whose value is the id of the element that labels the switch. If the page design does not call for a visible label for the switch, you will need to create a labelling element anyway, and then make it visually hidden.

• The "on" and "off" text will not be presented by screen readers and some assistive technologies. If the purpose and function of the switch are not obvious without that text, you may need to add visually hidden text to the switch's labelling element to make the purpose of the switch more clear.