Switch is a control that is used to quickly switch between two possible states. Switch works like a physical switch that allows users to turn things on or off, like a light switch.
How to use Switch
- use when a setting requires an on/off or show/hide function to display the results
- use when user needs to perform instantaneous actions that do not need a review or confirmation
- use when user is toggling independent features or behaviors
Using as a controlled input
For using the Switch as a controlled input, you need to:
- Pass the
isCheckedproperty, with this property it will already be a controlled component; - Pass a
onChangehandler, so you can use it to update the value ofisChecked;
Setting the isChecked will already define it as a controlled input.
const ExampleControlled = () => {const [switchState, setSwitchState] = useState(false);return (<Switchname="allow-cookies-controlled"id="allow-cookies-controlled"isChecked={switchState}onChange={() => setSwitchState((prevState) => !prevState)}>Allow cookies</Switch>);};
Using as an uncontrolled input
You can use the Switch as an uncontrolled input, for that you can:
- Set the
defaultCheckedproperty, it will ensure that the checked state can be altered normally. - Don't set the
isCheckedas it will make the input controlled.
<Switchtype="checkbox"name="allow-cookies-uncontrolled"id="allow-cookies-uncontrolled"defaultChecked={true}>Allow cookies</Switch>
Switch vs Checkbox
Switch is a two-step action: selection and execution, whereas checkbox is just selection of an option and its execution usually requires another control.
Code examples
Switch disabled
Accessibility
- use clear and concise label for Switch component
- if needed provide additional information for the user if Switch will cause a change in the context
Props
- Name
aria-label
DescriptionValue to be set as aria-label if not passing a children
string - Name
className
DescriptionCSS class to be appended to the root element
string - Name
defaultChecked
DescriptionDefines initial checked state for an uncontrolled component
falsetrue - Name
helpText
DescriptionOptional text to be added as help text bellow the label
string - Name
id
DescriptionSets the id of the input
string - Name
inputProps
DescriptionAdditional props that are passed to the input element
Partial<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>> - Name
isChecked
DescriptionDefines if the element is checked, onChange will be required
falsetrue - Name
isDisabled
DescriptionApplies disabled styles
falsetrue - Name
isInvalid
DescriptionApplies invalid styles
falsetrue - Name
isRequired
DescriptionValidate the input
falsetrue - Name
label
string - Name
name
DescriptionSet the name of the input
string - Name
onBlur
DescriptionAllows to listen to an event when an element loses focus
FocusEventHandler<HTMLInputElement | HTMLTextAreaElement> - Name
onChange
DescriptionAllows to listen to an input’s change in value
ChangeEventHandler<HTMLInputElement> - Name
onFocus
DescriptionAllows to listen to an event when an element get focused
FocusEventHandler<HTMLInputElement | HTMLTextAreaElement> - Name
onKeyDown
DescriptionAllows to listen to an event when a key is pressed
KeyboardEventHandler<HTMLInputElement | HTMLTextAreaElement> - Name
resize
DescriptionSets whether an element is resizable, and if so, in which directions
"none""both""horizontal""vertical" - Name
size
DescriptionSize of the input, only valid for switch input
"small""medium" - Name
testId
DescriptionA [data-test-id] attribute used for testing purposes
string - Name
value
DescriptionSet the value of the input
string - Name
willBlurOnEsc
DescriptionBoolean property that allows to blur on escape
falsetrue