Switch is a control that is used to quickly switch between two possible states. Use it when a setting requires an on/off or show/hide function to display the results; user needs to perform instantaneous actions that do not need a review or confirmation; user is toggling independent features or behaviors.

Import

import { Switch } from '@contentful/f36-components';
// or
import { Switch } from '@contentful/f36-forms';

Examples

Using as a controlled input

Controlled components in React are those in which form data is handled by the component’s state.

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.

Using as an uncontrolled input

Uncontrolled components are those for which the form data is handled by the DOM itself. “Uncontrolled” refers to the fact that these components are not controlled by React state.

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

Switch disabled

Props (API reference)

Name

Type

Default

aria-label
string

Value to be set as aria-label if not passing a children

className
string

CSS class to be appended to the root element

defaultChecked
false
true

Defines initial checked state for an uncontrolled component

helpText
string

Optional text to be added as help text bellow the label

id
string

Sets the id of the input

inputProps
Partial<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>>

Additional props that are passed to the input element

isChecked
false
true

Defines if the element is checked, onChange will be required

isDisabled
false
true

Applies disabled styles

isInvalid
false
true

Applies invalid styles

isRequired
false
true

Validate the input

label
string

name
string

Set the name of the input

onBlur
FocusEventHandler<HTMLInputElement | HTMLTextAreaElement>

Allows to listen to an event when an element loses focus

onChange
ChangeEventHandler<HTMLInputElement>

Allows to listen to an input’s change in value

onFocus
FocusEventHandler<HTMLInputElement | HTMLTextAreaElement>

Allows to listen to an event when an element get focused

onKeyDown
KeyboardEventHandler<HTMLInputElement | HTMLTextAreaElement>

Allows to listen to an event when a key is pressed

resize
"none"
"both"
"horizontal"
"vertical"

Sets whether an element is resizable, and if so, in which directions

size
"small"
"medium"

Size of the input, only valid for switch input

testId
string

A [data-test-id] attribute used for testing purposes

value
string

Set the value of the input

willBlurOnEsc
false
true

Boolean property that allows to blur on escape

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