Checkbox Group

A high-quality, unstyled React checkbox group component that provides a shared state for a series of checkboxes.

Provides shared state to a series of checkboxes.

Apples

FujiGalaGranny Smith

Usage guidelines

Form controls must have an accessible name: It can be created using <label> elements, or the Field and Fieldset components. See Labeling a checkbox group and the forms guide.

Anatomy

Checkbox Group is composed together with Checkbox. Import the components and place them together:

Anatomy

import { Checkbox } from '@base-ui/react/checkbox';
import { CheckboxGroup } from '@base-ui/react/checkbox-group';

<CheckboxGroup>
  <Checkbox.Root />
</CheckboxGroup>;

Examples

Labeling a checkbox group

Label the group with aria-labelledby and a sibling label element:

Using aria-labelledby to label a checkbox group

<div id="protocols-label">Allowed network protocols</div>
<CheckboxGroup aria-labelledby="protocols-label">{/* ... */}</CheckboxGroup>

An enclosing <label> is the simplest labeling pattern for each checkbox:

Using an enclosing label to label a checkbox

<label>
  <Checkbox.Root value="http" />
  HTTP
</label>

Rendering as a native button

By default, <Checkbox.Root> renders a <span> element to support enclosing labels. Prefer rendering each checkbox as a native button when using sibling labels (htmlFor/id).

Sibling label pattern with a native button

<div id="protocols-label">Allowed network protocols</div>
<CheckboxGroup aria-labelledby="protocols-label">
  <div>
    <label htmlFor="protocol-http">HTTP</label>
    <Checkbox.Root id="protocol-http" value="http" nativeButton render={<button />}>
      <Checkbox.Indicator />
    </Checkbox.Root>
  </div>
</CheckboxGroup>

Native buttons with wrapping labels are supported by using the render callback to avoid invalid HTML, so the hidden input is placed outside the label:

Render callback

<div id="protocols-label">Allowed network protocols</div>
<CheckboxGroup aria-labelledby="protocols-label">
  <Checkbox.Root
    value="http"
    nativeButton
    render={(buttonProps) => (
      <label>
        <button {...buttonProps} />
        HTTP
      </label>
    )}
  />
</CheckboxGroup>

Form integration

Use Field and Fieldset for group labeling and form integration:

Using Checkbox Group in a form

<Form>
  <Field.Root name="allowedNetworkProtocols">
    <Fieldset.Root render={<CheckboxGroup />}>
      <Fieldset.Legend>Allowed network protocols</Fieldset.Legend>
      <Field.Item>
        <Field.Label>
          <Checkbox.Root value="http" />
          HTTP
        </Field.Label>
      </Field.Item>
      <Field.Item>
        <Field.Label>
          <Checkbox.Root value="https" />
          HTTPS
        </Field.Label>
      </Field.Item>
      <Field.Item>
        <Field.Label>
          <Checkbox.Root value="ssh" />
          SSH
        </Field.Label>
      </Field.Item>
    </Fieldset.Root>
  </Field.Root>
</Form>

Parent checkbox

A checkbox that controls other checkboxes within a <CheckboxGroup> can be created:

Make <CheckboxGroup> a controlled component
Pass an array of all the child checkbox values to the allValues prop on the <CheckboxGroup> component
Add the parent boolean prop to the parent <Checkbox.Root>

ApplesFujiGalaGranny Smith

Nested parent checkbox

API reference

Root

Name	Type	Default	Description
`value`Optional	`string[] \| undefined`	—	Names of the checkboxes in the group that should be ticked. To render an uncontrolled checkbox group, use the `defaultValue` prop instead.
`defaultValue`Optional	`string[] \| undefined`	—	Names of the checkboxes in the group that should be initially ticked. To render a controlled checkbox group, use the `value` prop instead.
`allValues`Optional	`string[] \| undefined`	—	Names of all checkboxes in the group. Use this when creating a parent checkbox.
`disabled`Optional	`boolean \| undefined`	`false`	Whether the component should ignore user interaction.

Checkbox

A high-quality, unstyled React checkbox component that is easy to customize.

Collapsible

A high-quality, unstyled React collapsible component that displays a panel controlled by a button.

Checkbox Group

Root

On this page