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: CheckboxGroupChangeEventDetails, ) => 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

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: CheckboxGroup.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: CheckboxGroup.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 allValues prop on the <CheckboxGroup> component
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 <Field>
Use the render prop to compose <Fieldset> and <CheckboxGroup>
Use <Field.Item> to wrap each checkbox in the group

Using CheckboxGroup in a form

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