Skip to the content

FieldGroup

FieldGroup lays out a set of Checkbox or Radio items in a grid and controls them as one value. onChange receives the whole new value — a string[] for type="checkbox", a string for type="radio" — so a useState setter fits directly; never the event. color, label, labelProps and indeterminate are deprecated: they have no effect on FieldGroup.
Forms

When to use

Use when
  • A short list of checkboxes or radios comes from data ({ value, label }).
  • The items need columns or a set spacing.
  • The group is one field of a Form.
Avoid when
  • There is a single item — use Checkbox directly.
  • The list is long or searchable — use InputSelect.

Usage

const [channels, setChannels] = useState(['email']);

<FieldGroup
  type="checkbox"
  name="channels"
  value={channels}
  onChange={setChannels}
  columns={2}
  gap={{ row: 8, column: 24 }}
  inputs={[
    { value: 'email', label: 'E-mail' },
    { value: 'sms', label: 'SMS' },
  ]}
/>;

name is required: without it, onChange never fires. columns sets content-sized columns; without it the group is one full-width column. gap takes a spacing alias (default micro), a number (px) or { row, column }.

Radio group

With type="radio" every item receives the group name, so the browser keeps the choice exclusive.

<FieldGroup
  type="radio"
  name="plan"
  value={plan}
  onChange={setPlan}
  gap={8}
  inputs={[
    { id: 'plan-basic', value: 'basic', label: 'Basic' },
    { id: 'plan-pro', value: 'pro', label: 'Pro' },
  ]}
/>

For rich item content, pass Checkbox or Radio elements as children instead of inputs; the group still sets their checked and onChange from each child's value — set name and variant on each child yourself. With inputs, the group forwards variant to every item and, for radios, name.

Accessibility

  • Each item is a native checkbox or radio, focusable with Tab; radios sharing a name move with the arrow keys.
  • The root is role="group" (radiogroup for type="radio"); name it with aria-label or aria-labelledby.

Properties

Placement props (area, alignSelf, justifySelf) apply to the grid root; other layout props are ignored.

See also