Skip to content
Change the site theme
Figma
(information)

Switch

Peer review pending

A Switch is an interactive binary control.


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 label text to describe the purpose of the Switch. The label text shouldn't change when the state of the Switch changes. Help text can also be used to provide additional guidance.

  • 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.

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

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

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.

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.

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.

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.

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.

The default Switch state is off.

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.

Installation

Installation page anchor
yarn add @twilio-paste/switch - or - yarn add @twilio-paste/core
import {Switch, SwitchGroup} from '@twilio-paste/core/switch';
export const Basic = () => {
return (
<SwitchGroup name="bar" legend="This is the legend text" required disabled>
<Switch value="1" helpText="This is some help text.">
First
</Switch>
<Switch value="2" helpText="This is some help text.">
Second
</Switch>
<Switch value="3" helpText="This is some help text.">
Third
</Switch>
</SwitchGroup>
);
};

All the valid HTML attributes for input[type=checkbox] are supported including the following props:

PropTypeDescriptionDefault
childrenNonNullable<React.ReactNode>
id?stringnull
checked?booleannull
defaultChecked?booleannull
disabled?booleanfalse
hasError?booleanfalse
helpText?string \| ReactNodenull
required?booleanfalse
onChange?React.ChangeEventHandler<HTMLInputElement>null
element?stringOverrides the default element name to apply unique styles with the Customization Provider'SWITCH'

All the valid HTML attributes for label are supported including the following props:

PropTypeDescriptionDefault
childrenReactNode
legendstring \| NonNullable<React.ReactNode>
namestring
orientation?'vertical' \| 'horizontal''horizontal'
errorText?string \| React.ReactNodenull
helpText?string \| ReactNodenull
disabled?booleanfalse
required?booleanfalse
i18nRequiredLabel?string(required)
onChange?(checked: boolean) => voidnull
element?stringOverrides the default element name to apply unique styles with the Customization Provider'SWITCH_GROUP'

Black lives matter.