Switch

Version 5.1.1Github StorybookPeer review pending

A switch is an interactive binary control.

const SwitchExample = () => (
  <Switch name="settings" value="notifications">
    Notifications
  </Switch>
);

render(
  <SwitchExample />
)

Guidelines

About Switch

A Switch is an interactive binary control. It should be used in forms when an "on/off" or "yes/no" input is needed.

Use Switch when the interaction result is immediate. Users shouldn't need to perform an additional action (like use a "Save" or "Submit" button) to confirm Switch input. For example, when a user turns on a "Receive notifications" Switch, they should start receiving notifications immediately upon performing the action.

Use a Checkbox to present a user with a single binary choice that is part of a form or otherwise requires a user to take an additional action to confirm input.

Users expect the same immediate results from a digital toggle as they do from their real-world counterparts (e.g., light switches). Immediate results are a facet of toggle switches that grants users the freedom and control to update their preferences as needed.

Accessibility

SwitchGroup must have a legend that describes the collection.
Switch always has the role="switch" attribute.
Switch must have a visible label that is in close proximity to the control.
If you want to mark a Switch as required, use the required prop.
- Only use the required prop on the SwitchGroup if you want to mark the entire group as required.
- If you want to mark a single Switch as required, use the required prop on it directly.
- Ensure the label text includes wording that successfully describes the requirement to the user that they should toggle the Switch on
When in an error state display an inline error message below the offending Switch that clearly describes the error.
When displaying additional content based on toggling a Switch, be sure that the new content appears after the Switch in question so that it is naturally discoverable by assistive technology users.

Controlled vs. uncontrolled Switch

The Switch can either be controlled, meaning there is an external state that determines if the Switch is on or not, or uncontrolled, meaning the Switch manages its own state.

To make an uncontrolled Switch, you do not pass the checked or onChange prop.

const SwitchExample = () => {
  const switchRef = React.useRef(null);
  return (
    <Switch ref={switchRef} name="settings" value="notifications">
      Notifications
    </Switch>
  )
}

render(
  <SwitchExample />
)

To make a controlled Switch, you must pass the checked and onChange prop.

const SwitchExample = () => {
  const [on, setOn] = React.useState(false);

  return (
    <Switch checked={on} onChange={() => setOn(!on)}>
      Notifications
    </Switch>
  )
}
render(
  <SwitchExample />
)

Examples

Default

A Switch is always displayed with a visible label. The label text should never change based on the state of the Switch.

const SwitchExample = () => (
  <Switch name="settings" value="notifications">
    Notifications
  </Switch>
);

render(
  <SwitchExample />
)

With Help Text

In cases where the Switch requires additional context, you can display this information as help text below the Switch and label. This can help keep Switch labels concise. In order to maintain styling consistency, be sure to use the helpText prop here instead of using the Help Text component.

const SwitchExample = () => {
  return (
    <Switch value="privacy-program-enrollment" helpText={<Anchor href="#" showExternal>Read more about the program</Anchor>}>
      Enroll in Privacy Program
    </Switch>
  );
}

render(
  <SwitchExample />
)

Required

When a Switch is required to be 'on', a required indicator should be displayed alongside the label. The label text should also be written in such a way that this requirement is clear to the user.

const SwitchExample = () => {
  return (
    <Switch required value="newsletter-updates">Opt into newsletter updates</Switch>
  );
}

render(
  <SwitchExample />
)

Disabled

Use a disabled Switch to indicate to users that it is not interactive. If interactivity is dependent on another action, make that clear using help text.

const SwitchExample = () => {
  return (
    <Switch disabled helpText="Your account must have a verified email for this feature.">
      Enable email notifications
    </Switch>
  );
}

render(
  <SwitchExample />
)

Switch group

Multiple Switches and their labels are grouped together with a common group component. The group legend must be the first element inside the group. It must appear before any Switch or other content.

const SwitchExample = () => {
  const [checked1, setChecked1] = React.useState(true);
  const [checked2, setChecked2] = React.useState(false);
  const [checked3, setChecked3] = React.useState(true);

  return (
    <SwitchGroup
      name="email-notifications"
      legend={
        <Text as="span" color="currentColor">
          Adjust your email notification settings
        </Text>
      }
      helpText={<Text as="span">To learn more about configurable settings, visit our <Anchor href="#">help center</Anchor>.</Text>}
    >
      <Switch
        value="marketing-updates"
        checked={checked1}
        onChange={() => {
          setChecked1(!checked);
        }}
        helpText={
          <Text as="span" color="currentColor">
            Periodic sales and promotions from our partners.
          </Text>
        }
      >
        Marketing emails
      </Switch>
      <Switch
        value="product-updates"
        checked={checked2}
        onChange={() => {
          setChecked2(!checked2);
        }}
        helpText="Get the latest news and updates about our products."
      >
        Product updates
      </Switch>
      <Switch
        value="account-updates"
        checked={checked3}
        onChange={() => {
          setChecked3(!checked3);
        }}
        helpText="Get the latest news and updates about your account."
      >
        Account updates
      </Switch>
    </SwitchGroup>
  );
}

render(
  <SwitchExample />
)

Internationalization

To internationalize a Switch, simply pass different text to the Switch and SwitchGroup. The only exception to this is the required dot in the legend of a required SwitchGroup. To change the required dot's text, use the i18nRequiredLabel prop.

const SwitchExample = () => {
  return (
    <SwitchGroup
      orientation="horizontal"
      name="days"
      legend="Jours préférés"
      i18nRequiredLabel="(requis)"
      required
    >
      <Switch value="monday">
        Lundi
      </Switch>
      <Switch value="tuesday">
        Mardi
      </Switch>
      <Switch value="wednesday">
        Mercredi
      </Switch>
      <Switch value="thursday">
        Jeudi
      </Switch>
      <Switch value="friday">
        Vendredi
      </Switch>
    </SwitchGroup>
  )
}

render(
  <SwitchExample />
)

States

On

The default Switch state is off.

const SwitchExample = () => {
  const [checked, setChecked] = React.useState(true);

  return (
    <Switch checked={checked} onChange={() => setChecked(!checked)}>
      Enable SMS notifications
    </Switch>
  );
}

render(
  <SwitchExample />
)

Disabled on

Use the disabled on Switch to indicate to users that it is not interactive and cannot be turned off. If interactivity is dependent on another action, make that clear using help text.

const SwitchExample = () => {
  return (
    <Switch checked disabled helpText="Your account must have a verified email for this feature.">
      Enroll in paperless notifications
    </Switch>
  )
}
render(
  <SwitchExample />
)

Composition notes

Switch label text should indicate what the Switch does when it is on, but should not describe the state itself ("enabled", "disabled"). Label text shouldn't change when the state of the Switch changes.

Switch labels should be concise and put the most important information in the first few words. Avoid making the label a question.

Use Help Text for additional information, like any notable implications of turning on the Switch.