Switch
Use Switch for a setting that is on or off and takes effect right away, like notifications or auto-save. For a choice that applies when a form is submitted, use a Checkbox; for more than two states, use a SegmentedControl.
Switch turns one setting on or off. It is a role="switch" button: the knob slides to the end of the rail when on, and the rail takes the primary fill.
#Demos
#Basic
Give a switch an aria-label, or wrap it in a label with its text so clicking the text toggles it too.
#Size
#Shape
The rail is a pill by default; round={false} uses the theme’s corners.
#Loading
loading shows a spinner in the knob and ignores clicks. Use it while a change is being saved, and flip value once it is done.
#Disabled
#Content
checkedContent and uncheckedContent show text or an icon in the rail beside the knob. The rail grows to fit the longer one.
#Knob icon
icon shows in the knob in both states; checkedIcon and uncheckedIcon override it for one state.
#Custom values
checkedValue and uncheckedValue replace true and false, so the switch can hold any two strings or numbers.
Visibility: private
#Rubber band
While pressed, the knob stretches towards the other end. rubberBand={false} turns that off; it is also off while the knob shows an icon or a spinner.
#Controlled
Pass value and onUpdateValue to own the state.
Subscribed: yes
#Accessibility
The switch is a native button with role="switch" and aria-checked, so Space and Enter toggle it. Label it with aria-label, aria-labelledby or a wrapping label. The rail content is decorative and hidden from assistive tech. While loading the switch is aria-busy.
#Props
| Name | Type | Default | Description | Version |
|---|---|---|---|---|
value | string | number | boolean | undefined | Current value when controlled. | Unreleased |
defaultValue | string | number | boolean | uncheckedValue | Initial value when uncontrolled. | Unreleased |
onUpdateValue | (value) => void | undefined | Called with the new value when toggled. | Unreleased |
checkedValue | string | number | boolean | true | The value that means on. | Unreleased |
uncheckedValue | string | number | boolean | false | The value that means off. | Unreleased |
size | small | medium | large | medium | Rail and knob size. | Unreleased |
round | boolean | true | A pill rail and a round knob. | Unreleased |
disabled | boolean | false | Disables the switch. | Unreleased |
loading | boolean | false | Shows a spinner in the knob and ignores clicks. | Unreleased |
rubberBand | boolean | true | Stretches the knob while pressed. | Unreleased |
checkedContent | ReactNode | undefined | Shown in the rail while on. | Unreleased |
uncheckedContent | ReactNode | undefined | Shown in the rail while off. | Unreleased |
icon | ReactNode | undefined | Shown in the knob in both states. | Unreleased |
checkedIcon | ReactNode | undefined | Shown in the knob while on; overrides icon. | Unreleased |
uncheckedIcon | ReactNode | undefined | Shown in the knob while off; overrides icon. | Unreleased |
Switch also accepts native button attributes and a ref. Put content in the rail and knob with the checkedContent, uncheckedContent, icon, checkedIcon and uncheckedIcon props, and restyle the rail and knob through the --p-switch-* tokens.