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.

Switch has role="switch". The aria-labelledby attribute is automatically set on the component, which ensures that assistive technology devices can read the Switch's label. The 'aria-checked' attribute defaults to "false", and is set to "true" when the Switch is on.

Controlled vs. uncontrolle Switches

Controlled vs. uncontrolle Switches 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 onClick prop.

To make a controlled checkbox, you must pass the on and onChange props.

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.

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} from '@twilio-paste/core/switch';
export const Basic = () => {
return (
<SwitchContainer label="label text">
<Switch />
</SwitchContainer>
);
};

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

PropTypeDescriptionDefault
childrenReactNodenull
id?stringnull
disabled?boolean
element?stringOverrides the default element name to apply unique styles with the Customization Provider'SWITCH_CONTAINER'
helpText?ReactNode
labelReactNode
requiredboolean

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

PropTypeDescriptionDefault
childrenReactNodenull
id?stringnull
element?stringOverrides the default element name to apply unique styles with the Customization Provider'SWITCH'

Black lives matter.