Skip to main content

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 Checkbox when the option needs an indeterminate state. A Switch has none.
  • Prefer Choice when the switch needs a title and a description beside it.
  • Prefer ThemeSwitcher when 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:

PropTypeDefaultDescription
readOnly?booleanfalseMakes the switch immutable, meaning the user can not edit the control. Sets aria-readonly.
validation?"error" | "success" | "warning" | false | () => "error" | "success" | "warning" | falseUse the validation prop to show a specific validation status. This changes the color of the checked track and the focus ring, and stamps data-validation. The false type is useful with short-circuiting logic. Setting validation to "error" also sets aria-invalid.