Switch
Toggle an on/off setting with switch semantics and form values.
Anatomy#
Usage#
Use Switch for an on/off setting whose state is immediately meaningful. For an independent form choice that may be part of a set, use Checkbox. For a pressed command button, use ToggleButton.
Checked state and forms#
The focusable button has role="switch"; a hidden checkbox handles native form submission. Use
checked with onCheckedChange for controlled state, or defaultChecked for an initial value.
onCheckedChange fires only when the user toggles the switch, not for programmatic checked
changes or while the switch is disabled, readOnly, or loading.
trueValue and falseValue map checked state to domain values for checked, callbacks, and
schema-bound forms. Native form submission uses the separate value prop (default 'on') under
name only while checked; an unchecked switch contributes no entry.
Loading ownership#
While loading is set, the switch is non-interactive and shows loadingIcon on the thumb in place
of checkedIcon or uncheckedIcon. Drive loading from the application; the switch does not start
or track the async operation itself.
Examples#
Toggle deploy protection#
Keep the setting in local state with checked and onCheckedChange. Use defaultChecked only
when the switch owns its initial value.
Store a deployment gate as domain values#
Map on and off to application strings with trueValue and falseValue. Callbacks then receive
those strings instead of booleans.
Show a pending auto-deploy#
Drive loading from the in-flight request. The switch does not start an async operation by itself.
Mark on and off with icons#
Pass checkedIcon and uncheckedIcon to show a mark on the thumb for each state. Loading still
comes from application state.
Save auto-renewal#
Bind the switch to form.Field so submit reads a boolean from the schema.
API Reference#
Attributes#
data-checkeddata-disableddata-invaliddata-loadingdata-readonlydata-requireddata-uncheckedProps#
Props for the Switch component. Renders a <div> element by default.