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
Checkboxdirectly. - 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 anamemove with the arrow keys. - The root is
role="group"(radiogroupfortype="radio"); name it witharia-labeloraria-labelledby.
Properties
Name
Type
Default
Description
color"primary""secondary""tertiary""information""success""warning""danger"noneInteraction palette of the checked state (fill / ring / ink). Defaults
to the brand `primary`, like `Button` and `Tabs`. `variant` (`success` /
`error`) still wins when set.
@deprecated Has no effect on FieldGroup; removed in the next major.
columnsnumbernoneNumber of grid columns (`grid-template-columns: min-content × N`).
When absent, uses `1fr` (single column).
indeterminatebooleannoneMixed state — a dash on the checked fill, announced as `mixed` by
assistive technology (native `indeterminate` property). For a parent
whose children are only partly selected. The prop is the source of
truth: a click fires `onChange`, and the box stays mixed until you set
it to `false` from your state.
@deprecated Has no effect on FieldGroup; removed in the next major.
inputs({ label: string; } & Omit<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref">)[]nonelabelReactNodenoneText or element displayed next to the box. When a `string`, it is rendered
via `BaseText`; when a `ReactNode`, it is rendered as-is.
@deprecated Has no effect on FieldGroup (label each item in `inputs`); removed in the next major.
labelPropsPartial<TextInterface>noneTypography overrides for a string `label` (`fontSize`, `color`, …).
Ignored when `label` is a `ReactNode`.
@deprecated Has no effect on FieldGroup; removed in the next major.
namestringnoneGroup name. Every radio shares it (it defines the radio group); for
checkboxes each item keeps its own `name` from `inputs`. Required for
`onChange` to fire.
onChange((value: string[]) => void)((value: string) => void)noneReceives the whole new value — the array of checked values. Never the
event. A `useState<string[]>` setter fits.
Receives the whole new value — the selected radio's value. Never the
event. A `useState<string>` setter fits.
type *"checkbox""radio"noneType of the items.
value *stringstring[]noneSelected value.
- For `type="checkbox"`: array of strings.
- For `type="radio"`: single string.
variant"success""default""error"'default'Visual variant of the input — reflects the validation state.
Placement props (area, alignSelf, justifySelf) apply to the grid root; other layout props are ignored.