Checkbox Group

Provides shared state to a series of checkboxes.

Apples

FujiGalaGranny Smith

import * as React from 'react';
import { Checkbox } from '@base-ui-components/react/checkbox';
import { CheckboxGroup } from '@base-ui-components/react/checkbox-group';
import styles from './index.module.css';

export default function ExampleCheckboxGroup() {
  return (
    <CheckboxGroup
      aria-labelledby="apples-caption"
      defaultValue={['fuji-apple']}
      className={styles.CheckboxGroup}
    >
      <div className={styles.Caption} id="apples-caption">
        Apples
      </div>

      <label className={styles.Item}>
        <Checkbox.Root name="apple" value="fuji-apple" className={styles.Checkbox}>
          <Checkbox.Indicator className={styles.Indicator}>
            <CheckIcon className={styles.Icon} />
          </Checkbox.Indicator>
        </Checkbox.Root>
        Fuji
      </label>

      <label className={styles.Item}>
        <Checkbox.Root name="apple" value="gala-apple" className={styles.Checkbox}>
          <Checkbox.Indicator className={styles.Indicator}>
            <CheckIcon className={styles.Icon} />
          </Checkbox.Indicator>
        </Checkbox.Root>
        Gala
      </label>

      <label className={styles.Item}>
        <Checkbox.Root name="apple" value="granny-smith-apple" className={styles.Checkbox}>
          <Checkbox.Indicator className={styles.Indicator}>
            <CheckIcon className={styles.Icon} />
          </Checkbox.Indicator>
        </Checkbox.Root>
        Granny Smith
      </label>
    </CheckboxGroup>
  );
}

function CheckIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg fill="currentcolor" width="10" height="10" viewBox="0 0 10 10" {...props}>
      <path d="M9.1603 1.12218C9.50684 1.34873 9.60427 1.81354 9.37792 2.16038L5.13603 8.66012C5.01614 8.8438 4.82192 8.96576 4.60451 8.99384C4.3871 9.02194 4.1683 8.95335 4.00574 8.80615L1.24664 6.30769C0.939709 6.02975 0.916013 5.55541 1.19372 5.24822C1.47142 4.94102 1.94536 4.91731 2.2523 5.19524L4.36085 7.10461L8.12299 1.33999C8.34934 0.993152 8.81376 0.895638 9.1603 1.12218Z" />
    </svg>
  );
}

Anatomy

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

Anatomy

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

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

API reference

defaultValue

string[]

Name: defaultValue
Description: Names of the checkboxes in the group that should be initially ticked.

To render a controlled checkbox group, use the value prop instead.
Type: string[] | undefined

value

string[]

Name: value
Description: Names of the checkboxes in the group that should be ticked.

To render an uncontrolled checkbox group, use the defaultValue prop instead.
Type: string[] | undefined

onValueChange

function

Name: onValueChange
Description: Event handler called when a checkbox in the group is ticked or unticked. Provides the new value as an argument.
Type: | (( value: string[], eventDetails: Checkbox.Group.ChangeEventDetails, ) => void) | undefined

allValues

string[]

Name: allValues
Description: Names of all checkboxes in the group. Use this when creating a parent checkbox.
Type: string[] | undefined

disabled

boolean

(default:

false

)

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean | undefined
Default: false

className

string | function

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: string | ((state: Checkbox.Group.State) => string)

render

ReactElement | function

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Checkbox.Group.State, ) => ReactElement)

data-disabled

Present when the checkbox group is disabled.

Attribute	Description
`data-disabled`	Present when the checkbox group is disabled.

Examples

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 CheckboxGroup’s allValues prop
Add the parent boolean prop to the parent Checkbox

ApplesFujiGalaGranny Smith

import * as React from 'react';
import { Checkbox } from '@base-ui-components/react/checkbox';
import { CheckboxGroup } from '@base-ui-components/react/checkbox-group';
import styles from './index.module.css';

const fruits = ['fuji-apple', 'gala-apple', 'granny-smith-apple'];

export default function ExampleCheckboxGroup() {
  const [value, setValue] = React.useState<string[]>([]);

  return (
    <CheckboxGroup
      aria-labelledby="apples-caption"
      value={value}
      onValueChange={setValue}
      allValues={fruits}
      className={styles.CheckboxGroup}
      style={{ marginLeft: '1rem' }}
    >
      <label className={styles.Item} id="apples-caption" style={{ marginLeft: '-1rem' }}>
        <Checkbox.Root className={styles.Checkbox} name="apples" parent>
          <Checkbox.Indicator
            className={styles.Indicator}
            render={(props, state) => (
              <span {...props}>
                {state.indeterminate ? (
                  <HorizontalRuleIcon className={styles.Icon} />
                ) : (
                  <CheckIcon className={styles.Icon} />
                )}
              </span>
            )}
          />
        </Checkbox.Root>
        Apples
      </label>

      <label className={styles.Item}>
        <Checkbox.Root value="fuji-apple" className={styles.Checkbox}>
          <Checkbox.Indicator className={styles.Indicator}>
            <CheckIcon className={styles.Icon} />
          </Checkbox.Indicator>
        </Checkbox.Root>
        Fuji
      </label>

      <label className={styles.Item}>
        <Checkbox.Root value="gala-apple" className={styles.Checkbox}>
          <Checkbox.Indicator className={styles.Indicator}>
            <CheckIcon className={styles.Icon} />
          </Checkbox.Indicator>
        </Checkbox.Root>
        Gala
      </label>

      <label className={styles.Item}>
        <Checkbox.Root value="granny-smith-apple" className={styles.Checkbox}>
          <Checkbox.Indicator className={styles.Indicator}>
            <CheckIcon className={styles.Icon} />
          </Checkbox.Indicator>
        </Checkbox.Root>
        Granny Smith
      </label>
    </CheckboxGroup>
  );
}

function CheckIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg fill="currentcolor" width="10" height="10" viewBox="0 0 10 10" {...props}>
      <path d="M9.1603 1.12218C9.50684 1.34873 9.60427 1.81354 9.37792 2.16038L5.13603 8.66012C5.01614 8.8438 4.82192 8.96576 4.60451 8.99384C4.3871 9.02194 4.1683 8.95335 4.00574 8.80615L1.24664 6.30769C0.939709 6.02975 0.916013 5.55541 1.19372 5.24822C1.47142 4.94102 1.94536 4.91731 2.2523 5.19524L4.36085 7.10461L8.12299 1.33999C8.34934 0.993152 8.81376 0.895638 9.1603 1.12218Z" />
    </svg>
  );
}

function HorizontalRuleIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg
      width="10"
      height="10"
      viewBox="0 0 24 24"
      fill="currentcolor"
      xmlns="http://www.w3.org/2000/svg"
      {...props}
    >
      <line
        x1="3"
        y1="12"
        x2="21"
        y2="12"
        stroke="currentColor"
        strokeWidth={3}
        strokeLinecap="round"
      />
    </svg>
  );
}

Nested parent checkbox

Form integration

To use checkbox group in a form:

Pass the group’s name to a Field
Use Field.Label to label each checkbox
Use the render prop to render the field as a Fieldset in order to label the group

Using CheckboxGroup in a form

<Form>
  <Field.Root name="toppings" render={<Fieldset.Root />}>
    <Fieldset.Legend>Toppings</Fieldset.Legend>
    <CheckboxGroup>
      <Field.Label>
        <Checkbox.Root value="anchovies" />
        Anchovies
      </Field.Label>
      <Field.Label>
        <Checkbox.Root value="olives" />
        Olives
      </Field.Label>
    <CheckboxGroup>
  </Field.Root>
</Form>