Switch primitive
Lower-level switch anatomy for custom label layouts.
Use the Switch primitive when your layout owns the label, such as a settings row, or when the label
needs custom content. For a normal labelled switch, use
SwitchField.
Anatomy
SwitchRoot is the semantic root. It owns the selection, state, validation, form, and size props.
id, className, and ref target the root element. inputId and inputRef target the input.
SwitchLabel is the clickable native <label>. It holds the hidden input, SwitchControl, and
usually the label text. Like React Aria's SwitchButton, it takes className, style, and
children as functions of the switch state, as well as render, slot, and event handlers.
SwitchControl draws the track, and SwitchThumb draws the thumb that moves along it. Pass
children to SwitchThumb to draw inside the thumb. Put the control before the label text.
Description and error
Wrap SwitchLabel in InlineField to add a description and an
errorMessage. The errorMessage shows while the root is invalid. For a custom arrangement, place
FieldDescription and FieldError inside the root instead of InlineField.
Labels from the layout
When another part of the layout draws the visible label and description, leave the text out of
SwitchLabel. Place a FieldLabel and a FieldDescription
anywhere inside SwitchRoot. The root connects them to the input, so the label names the switch,
clicking it toggles the switch, and the description describes it. Pass no ids.
Put the label text in either SwitchLabel or FieldLabel, not both. The switch's name joins the
text from each.
SwitchLabel is a native <label>, so it takes textual, non-interactive content only. Place links
and buttons outside it. Set slot={null} on each Text you place in it, as the
Checkbox primitive describes.
SwitchLabel draws no required marker. With isRequired on SwitchRoot, a FieldLabel does, as
Required fields describes. Show the required
state in your own content when you use SwitchLabel for the text.
API
SwitchRootProps
SwitchRootProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.
Prop
Type
SwitchLabelProps
SwitchLabelProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.
SwitchControlProps
SwitchControlProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.
SwitchThumbProps
SwitchThumbProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.