Skip to main content
Use Switch for an on or off preference. Give the control a visible label or an accessible name.

​
Uncontrolled state

​
Controlled state

onCheckedChange receives the next boolean and event details. The size prop accepts sm or md and defaults to md.

​
Keyboard and forms

Tab moves focus to the switch; Space toggles it. Clicking its associated label also toggles it. Use disabled to prevent interaction or readOnly to retain a focusable control whose value cannot be changed. A named switch submits its value when checked. Use value to customize that value, and uncheckedValue if the form should also submit a value when it is off.

​
Props

The reference includes component-specific and inherited Base UI props. Native attributes such as aria-label and data-* are also accepted.
​
boolean
Whether the switch is currently active.To render an uncontrolled switch, use the defaultChecked prop instead.
​
string | ((state: SwitchRootState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
​
boolean
default:"false"
Whether the switch is initially active.To render a controlled switch, use the checked prop instead.
​
boolean
default:"false"
Whether the component should ignore user interaction.
​
string
Identifies the form that owns the hidden input. Useful when the switch is rendered outside the form.
​
string
The id of the hidden input element.When nativeButton is true, the id is applied to the root element.
​
Ref<HTMLInputElement>
A ref to access the hidden <input> element.
​
string
Identifies the field when a form is submitted.
​
boolean
default:"false"
Whether the component renders a native <button> element when replacing it via the render prop. Set to true if the rendered element is a native button.
​
((checked: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)
Event handler called when the switch is activated or deactivated.
​
boolean
default:"false"
Whether the user should be unable to activate or deactivate the switch.
​
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SwitchRootState>
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.
​
boolean
default:"false"
Whether the user must activate the switch before submitting a form.
​
"sm" | "md"
default:"md"
Visual size of the switch.
​
CSSProperties | ((state: SwitchRootState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.
​
string
The value submitted with the form when the switch is off. By default, unchecked switches do not submit any value, matching native checkbox behavior.
​
string
The value submitted with the form when the switch is on. By default, switch submits the “on” value, matching native checkbox behavior.