Checkbox Group

Provides shared state to a series of checkboxes.

Apples

FujiGalaGranny Smith

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

export default function ExampleCheckboxGroup() {
  const id = React.useId();
  return (
    <CheckboxGroup
      aria-labelledby={id}
      defaultValue={['fuji-apple']}
      className={styles.CheckboxGroup}
    >
      <div className={styles.Caption} id={id}>
        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>
  );
}

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>

The group controls the parent checkbox’s indeterminate state when some, but not all, child checkboxes are checked.

ApplesFujiGalaGranny Smith

index.tsx index.module.css theme.css

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

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

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

  return (
    <CheckboxGroup
      aria-labelledby={id}
      value={value}
      onValueChange={setValue}
      allValues={fruits}
      className={styles.CheckboxGroup}
      style={{ marginLeft: '1rem' }}
    >
      <label className={styles.Item} id={id} style={{ marginLeft: '-1rem' }}>
        <Checkbox.Root className={styles.Checkbox} 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

API reference

defaultValuestring[]—

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

valuestring[]—

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

onValueChangefunction—

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: CheckboxGroup.ChangeEventDetails, ) => void) | undefined

allValuesstring[]—

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

disabledbooleanfalse

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

classNamestring | 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 | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: CheckboxGroup.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | 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) | undefined

data-disabled

Present when the checkbox group is disabled.

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

CheckboxGroup.PropsHide

Re-Export of CheckboxGroup props as CheckboxGroupProps

CheckboxGroup.StateHide

type CheckboxGroupState = {
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
}

CheckboxGroup.ChangeEventReasonHide

type CheckboxGroupChangeEventReason = 'none'

CheckboxGroup.ChangeEventDetailsHide

type CheckboxGroupChangeEventDetails = {
  /** The reason for the event. */
  reason: 'none';
  /** The native event associated with the custom event. */
  event: Event;
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
}