const SwitchExample = () => (<Switch name="settings" value="notifications">Notifications</Switch>);render(<SwitchExample />)
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.
[U]sers 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
legendthat 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
requiredprop.- Only use the
requiredprop 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
requiredprop on it directly. - Ensure the label text includes wording that successfully describes the requirement to the user that they should toggle the Switch on
- Only use the
- 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.
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 />)
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 />)
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 />)
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 />)
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 />)
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 (<SwitchGroupname="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>}><Switchvalue="marketing-updates"checked={checked1}onChange={() => {setChecked1(!checked);}}helpText={<Text as="span" color="currentColor">Periodic sales and promotions from our partners.</Text>}>Marketing emails</Switch><Switchvalue="product-updates"checked={checked2}onChange={() => {setChecked2(!checked2);}}helpText="Get the latest news and updates about our products.">Product updates</Switch><Switchvalue="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.
const SwitchExample = () => {return (<SwitchGrouporientation="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.
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.
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.