Switch

The Switch component allows users to create a switch to represent boolean states.

Basic usage

You can access the value of a Switch using its component state.

Disabling

A Switch can be disabled using the defaultDisabled prop.

Inner labels

Inner labels for the checked and unchecked states of the Switch can be added through the onLabel and offLabel props.

Setting values

If you need to update values programmatically, you should use the setChecked and setDisabled functions on the state.

Component API

NameDescriptionDefault
id
string
The ID referenced by the global component state.
defaultDisabled
boolean
Whether the switch is initially disabled.
defaultChecked
boolean
Whether the switch is initially checked.
validate
((value: boolean) => string | undefined) | Array<(value: boolean) => string | undefined>
A single function or an array of functions that validate the input value.
required
boolean
Adds red asterisk on the right side of label and sets required on input element
false
onChange
(value: boolean) => void
Callback when checked state changes when using as a controlled component. Prefer using the global component state.
size
"xs" | "sm" | "md" | "lg" | "xl"
Size of the switch.
color
"primary" | "secondary" | "dark" | "gray" | "red" | "pink" | "grape" | "violet" | "indigo" | "blue" | "cyan" | "teal" | "green" | "lime" | "yellow" | "orange" | "success" | "error" | `primary.${number}` | `secondary.${number}` | `dark.${number}` | `gray.${number}` | `red.${number}` | `pink.${number}` | `grape.${number}` | `violet.${number}` | `indigo.${number}` | `blue.${number}` | `cyan.${number}` | `teal.${number}` | `green.${number}` | `lime.${number}` | `yellow.${number}` | `orange.${number}` | `success.${number}` | `error.${number}`
Color of the switch.
label
Component
Switch label. Can be a string or a React component.
description
Component
Description displayed below the switch. Can be a string or a React component.
checked
boolean
Whether the switch is checked when using as a controlled component. Prefer using defaultChecked and the global component state.
error
Component
Displays error message after the switch input. Can be a string or a React component.
offLabel
Component
Inner label when the switch is unchecked. Can be a string or a React component.
onLabel
Component
Inner label when the switch is checked. Can be a string or a React component.
sx
CSSObject
CSS style overrides.
width
number | "content" | "auto" | `${number}%` | `${number}/${number}` | { xs?: ColWidth; sm?: ColWidth; md?: ColWidth; lg?: ColWidth; xl?: ColWidth; }
Width of the component. This component must be a direct child of a <Stack> for this prop to take effect. If an integer is specified, signifies the width in a 12 item grid. 12 means that the component takes up the entire row, 6 is half, 1 is 1/12. If a decimal or fraction is specified, signifies the fractional share of the row. e.g. 1/2 takes up half of the row. If a percentage is specified, signifies the percentage share of the row. e.g. "50%" takes up half of the row. content indicates that the component should take up as much space as its content. auto indicates that the component should take any leftover space on the row. To set width based on the screen size, use an object with a specific width for each breakpoint. e.g. {xs: "100%", md: "50%"} sets the width on xs-md screens to 100% and md and larger screens to 50%.
content
offset
number | `${number}%` | `${number}/${number}` | { xs?: ColOffset; sm?: ColOffset; md?: ColOffset; lg?: ColOffset; xl?: ColOffset; }
Creates a gap to the left of the component. Has the same units as width. This component must be a direct child of a <Stack> for this prop to take effect. If an integer is specified, signifies the offset in a 12 item grid. 6 means the component is offset by half a row, 1 is 1/12 of a row. If a decimal or fraction is specified, signifies the fractional share of the row. e.g. 1/2 offsets a component by half of the row. If a percentage is specified, signifies the percentage share of the row. e.g. "50%" offsets a component by half of the row. To set offset based on the screen size, use an object with a specific offset for each breakpoint. e.g. {xs: "50%", md: "0%"} sets the offset on xs-md screens to 50% and md and larger screens to 0%.

State API

NameDescription
checked
boolean
Whether the switch is checked
setChecked
(checked: boolean) => void
Sets the value of the switch
disabled
boolean
Whether the switch is disabled
setDisabled
(disabled?: boolean) => void
Sets the disabled value of the switch. If the `disabled` value is not provided, the switch will be disabled