Checkbox Field
Lets someone select an independent option, with optional supporting and validation text.
Use CheckboxField when someone can choose an option independently of nearby controls. Pass label
to name the option, and description to clarify what it means.
Labels
Every CheckboxField has a visible label. The label sits inside a native <label>, so pass
textual content only. Place links and buttons next to the checkbox. Inline typography such as
Strong works inside the label. Set slot={null} on a Text you place there, as the
Checkbox primitive describes.
When another part of the layout draws the visible label, such as a table row or a settings row,
compose the Checkbox primitive and name the control with
aria-labelledby.
States
Use defaultSelected for an uncontrolled initial value, or pair isSelected with onChange when
application state owns the selection. isIndeterminate communicates a mixed state, such as a parent
option whose child options are only partly selected.
Size
Use size to change the checkbox control. It does not change the label typography. medium is the
default. Use small in compact layouts and large where a larger control improves scanning.
Validation
Set isRequired to require the choice. CheckboxField shows its validation message after
validation fails. Pass errorMessage only for an error you already have, such as one from a form
library or your server. A non-empty message marks the checkbox invalid. Read
Validation for where messages come from and how to write them.
Required marker
A required checkbox shows a marker after its label. Read
Required fields for both necessityIndicator
values.
Labels with Text
Wrap a checkbox in block Text when its label needs a specific text size. The control follows the
inherited line height. It keeps its fixed visual square centred on the first line when the label
wraps. Outside Text, it uses the normal compact control size.
IDs and refs
id, className, and ref target the root element. inputId and inputRef target the input.
Form values
Pass name so the checkbox joins FormData when selected. Pass value to set the submitted value,
and form to associate a checkbox with a <form> it does not sit inside.
Accessibility
Disabled checkboxes cannot receive focus, and their value cannot change. Read-only checkboxes remain focusable, so someone who uses a keyboard or assistive technology can still perceive their state. Keyboard navigation shows a focus ring. Pointer focus does not.
API
CheckboxFieldProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.
Prop
Type