Switch
A form control that toggles one setting on or off. Pair it with Field to connect its label, description, and errors in a form.
When to use
- Turn one setting on or off, such as a feature toggle in a settings list.
- Prefer
Checkboxwhen the option needs an indeterminate state. ASwitchhas none. - Prefer
Choicewhen the switch needs a title and a description beside it. - Prefer
ThemeSwitcherwhen the setting is the light or dark theme.
Without a Field
Render the control on its own, with a Label as its caption:
Multi-line label with description
For a switch with an emphasized title and a supplementary description beneath it, compose it inside Choice: drop the Switch into Choice.Indicator and pair Choice.Label (a real <label>; clicking it flips the switch, since a <button role="switch"> is a labelable element) with an optional Choice.Description. The switch aligns to the leading of the title's first line, and the description associates via aria-describedby.
Inside a Field
Wrap that same Choice in a Field.Item / Field.Control to bind a form name and pick up validation. The field's id / name / aria-* flow onto the switch, and the Field.Description (or a Field.Errors) is merged into the control's aria-describedby alongside the Choice.Description:
See the Choice docs for the clickable-row variant and the full API.
Examples
Switch in a form with client-side validation
In this example, the Switch is used in a form with client-side validation. The form is built using @tanstack/react-form and zod for validation. The form accepts and validates the input before submission.
API Reference
Switch
The Switch is built on top of Radix Switch. It exposes the same API with the following additional props: