CheckboxGroup
Collect multiple choices as one array-valued field.
Anatomy#
The nested <fieldset> owns group semantics and the optional <legend> association.
Usage#
Use CheckboxGroup for several choices submitted as one array. Use individual Checkbox controls when the fields are independent. Use RadioGroup when only one option may be selected.
Selection model#
The group value is an array of item values. Pair value with onValueChange for controlled
selection, or set defaultValue when the group owns its initial state. onValueChange receives the
complete next array and fires only for user toggles. A disabled group disables all items; an item
can also be disabled independently.
items accepts objects with value, label, description, disabled, indeterminate,
checkedIcon, and indeterminateIcon. A string is shorthand for an item whose value and label
are that string. Item value must be unique. An item without a value falls back to its index.
Forms#
Give the group a name for native form submission, or place it inside form.Field from
createForm for schema binding. Standalone Field supplies
labels and messages without validation. With required, the group is valid when at least one
enabled item is selected. Each checkbox keeps its own tab stop; the group does not use radio-style
arrow navigation.
Layout and indicator#
variant is list (default), card, or table. card draws each item as a bordered card that
toggles when clicked, and table joins bordered cards into one connected block. orientation
(vertical by default, or horizontal) sets the layout direction, and size accepts sm, md
(default), or lg.
indicatorPosition places the check mark at the leading (default) or trailing edge, or hides it
visually with hidden.
Examples#
Choose notification channels#
Keep the group value as an array of channel ids. Pair value with onValueChange when the page
owns the selection.
Assign locked team roles#
Disable an item that must stay selected. The controlled value still includes that item, and the
user cannot remove it.
Require at least one permission#
Bind the array to form.Field and reject an empty selection with a minLength schema rule.
Put the check at the end of alert cards#
indicatorPosition="trailing" places the check after the label on variant="card". Use it when the card reads as
a row with the control on the trailing edge.
API Reference#
Attributes#
data-disableddata-invaliddata-readonlydata-requireddata-checkeddata-indeterminatedata-uncheckedProps#
Props for the CheckboxGroup component. Renders a <div> element by default.