[CheckboxGroup] Multiple required child checkboxes are not all validated

[nami8824]

Bug report

Current behavior

When multiple Checkbox.Root components inside a CheckboxGroup are marked as required, validation can incorrectly pass after only one of the required checkboxes is checked.

As a result, the Field.Root can be considered valid even while another required checkbox in the same group is still unchecked.

Expected behavior

Each required child checkbox inside a CheckboxGroup should continue to enforce its own required constraint.

For example, if two child checkboxes are marked as required, checking only one of them should not make the Field.Root valid while the other required checkbox remains unchecked.

Reproducible example

A failing test case reproduces the issue:

packages/react/src/checkbox-group/CheckboxGroup.test.tsx

it('does not clear the required error when another required child checkbox is unchecked', async () => {
  const { user } = render(
    <Form>
      <Field.Root name="apple">
        <Fieldset.Root render={<CheckboxGroup defaultValue={[]} />}>
          <Fieldset.Legend>Allowed network protocols</Fieldset.Legend>
          <Field.Item>
            <Field.Label>
              <Checkbox.Root value="one" data-testid="checkbox" required />
              HTTP
            </Field.Label>
          </Field.Item>
          <Field.Item>
            <Field.Label>
              <Checkbox.Root value="two" data-testid="checkbox" required />
              HTTPS
            </Field.Label>
          </Field.Item>
        </Fieldset.Root>
        <Field.Error match="valueMissing" data-testid="error">
          required
        </Field.Error>
      </Field.Root>
      <button type="submit">submit</button>
    </Form>,
  );

  const checkboxes = screen.getAllByTestId('checkbox');

  await user.click(screen.getByText('submit'));
  expect(screen.getByTestId('error')).toHaveTextContent('required');

  await user.click(checkboxes[1]);
  await user.click(screen.getByText('submit'));

  expect(screen.getByTestId('error')).toHaveTextContent('required');
});

The test fails with TestingLibraryElementError: Unable to find an element by: [data-testid="error"] on the final assertion, because Field.Error is removed after only the second required checkbox is checked.

Base UI version

v1.5.0

Which browser are you using?

Reproduced in the test environment.

Which OS are you using?

macOS

Which assistive tech are you using (if applicable)?

N/A

Additional context

The issue seems related to how Field.Root tracks a single validation input ref. Multiple checkbox inputs inside the same field can register with that ref, but only one input ultimately becomes the active validation target.

[spokodev]

I traced this. The root cause is that CheckboxGroup shares one validation.inputRef across all child checkboxes, so the field's commit logic only ever inspects whichever child last assigned the ref, not all required children.

Code path:

1. useFieldValidation declares a single inputRef at packages/react/src/field/root/useFieldValidation.ts:59 and exposes it on the returned validation object.
2. Each CheckboxRoot merges this ref into its hidden input at packages/react/src/checkbox/root/CheckboxRoot.tsx:175. With N children, the last child to mount or re-render wins the ref.
3. CheckboxGroup registers as a single field control at packages/react/src/checkbox-group/CheckboxGroup.tsx:109 and calls validation.change(resolvedValue) at line 118.
4. The commit short-circuits at useFieldValidation.ts:103: when inputRef.current.validity.valueMissing is false, it marks the whole field valid. With two required children, checking the one whose input happens to hold the ref clears valueMissing on that input, and the field is considered valid even though the other required child is still unchecked.

CheckboxRoot's useRegisterFieldControl(controlRef, id, checked, undefined, !groupContext && !disabled, nameProp) at line 172 deliberately skips per-child registration when in a group, so the field never sees individual children.

Fix-shape options:

1. Track required children inside CheckboxGroup and wrap validation. Expose a requiredChildInputs: Set<HTMLInputElement> on CheckboxGroupContext. Each CheckboxRoot registers its input when required && groupContext, unregisters on unmount. CheckboxGroup then provides a wrapped validation whose commit logic walks every required child's validity before deciding valueMissing is cleared. Touches CheckboxGroupContext, CheckboxRoot, CheckboxGroup; doesn't change useFieldValidation.

2. Register each required child as its own field control even in a group. Loosen the condition at CheckboxRoot.tsx:172 so required children always register with the field. The field would then have one control per required child plus the group; the validation needs to walk all registered controls rather than just validation.inputRef.current. Smaller per-component diff but pushes the multi-input awareness down into useFieldValidation and field-register-control internals.

3. Make inputRef a multi-ref Set inside useFieldValidation. Replace the single React.useRef<HTMLInputElement | null> with a registration API that tracks all inputs participating in the field, and update each element.validity.valueMissing check site (lines 101 to 168, plus 233) to walk the set. Largest internal change but generalizes beyond CheckboxGroup.

Option 1 is the smallest scope but introduces a CheckboxGroup-specific concept. Option 2 generalizes to "any composite control" but requires plumbing across field internals. Option 3 is cleanest at the validation layer but biggest blast radius.

Which direction would you prefer? I can put up a PR once you point.

[mj12albert]

@nami8824 I would suggest using a custom validate function on Field for this case

There isn't any web platform equivalent of a checkbox group, so to achieve this we'd need to somehow aggregate multiple native checkbox valueMissing states into a single field level state that can be rendered by <Field.Error match="valueMissing" /> on the group

(IMO this isn't a bug)