This is version 4 beta of Forma 36Go back to last stable version 3
Forma 36

Switch

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.

Table of contents

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 isChecked property, with this property it will already be a controlled component;
  • Pass a onChange handler, so you can use it to update the value of isChecked;

Setting the isChecked will already define it as a controlled input.

const ExampleControlled = () => {
const [switchState, setSwitchState] = useState(false);
return (
<Switch
name="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 defaultChecked property, it will ensure that the checked state can be altered normally.
  • Don't set the isChecked as it will make the input controlled.
<Switch
type="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

NameRequiredDefaultTypeDescription
aria-labelstringValue to be set as aria-label if not passing a children
defaultCheckedfalse
false
true
Defines initial checked state for an uncontrolled component
helpTextstringOptional text to be added as help text bellow the label
idstringSets the id of the input
inputPropsPartial<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>>Additional props that are passed to the input element
isCheckedundefined
false
true
Defines if the element is checked, onChange will be required
isDisabledfalse
false
true
Applies disabled styles
isInvalidfalse
false
true
Applies invalid styles
isRequiredfalse
false
true
Validate the input
labelstring
namestringSet the name of the input
onBlurFocusEventHandler<HTMLInputElement | HTMLTextAreaElement>Allows to listen to an event when an element loses focus
onChangeChangeEventHandler<HTMLInputElement>Allows to listen to an input’s change in value
onFocusFocusEventHandler<HTMLInputElement | HTMLTextAreaElement>Allows to listen to an event when an element get focused
onKeyDownKeyboardEventHandler<HTMLInputElement | HTMLTextAreaElement>Allows to listen to an event when a key is pressed
resizevertical"none" | "both" | "horizontal" | "vertical"Sets whether an element is resizable, and if so, in which directions
sizemedium
"small"
"medium"
Size of the input, only valid for switch input
valuestringSet the value of the input
willBlurOnEsctrue
false
true
Boolean property that allows to blur on escape
classNamestringCSS class to be appended to the root element
styleCSSPropertiesAccepts a JavaScript object with camelCased properties rather than a CSS string
testIdstringA [data-test-id] attribute used for testing purposes