Skip to contentSkip to navigationSkip to topbar
Paste assistant Assistant
Figma
Star

Switch

Version 5.1.1GithubStorybookPeer review pending

A switch is an interactive binary control.

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

Guidelines

Guidelines page anchor

About Switch

About Switch page anchor

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.

  • 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

Controlled vs. uncontrolled Switch page anchor

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.

Component preview theme
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.

Component preview theme
const SwitchExample = () => {
const [on, setOn] = React.useState(false);
return (
<Switch checked={on} onChange={() => setOn(!on)}>
Notifications
</Switch>
)
}
render(
<SwitchExample />
)

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

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

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.

Component preview theme
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 />
)

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.

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

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.

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

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.

Component preview theme
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 />
)

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.

Component preview theme
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 />
)

The default Switch state is off.

Component preview theme
const SwitchExample = () => {
const [checked, setChecked] = React.useState(true);
return (
<Switch checked={checked} onChange={() => setChecked(!checked)}>
Enable SMS notifications
</Switch>
);
}
render(
<SwitchExample />
)

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.

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

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.