@base-ui/react 1.6.0 → 1.7.0

package/checkbox/indicator/CheckboxIndicatorDataAttributes.mjs

@@ -25,7 +25,7 @@ export let CheckboxIndicatorDataAttributes = function (CheckboxIndicatorDataAttr
    */
   CheckboxIndicatorDataAttributes["required"] = "data-required";
   /**
-   * Present when the checkbox indicator is animating in.
+   * Present when the checkbox indicator begins animating in.
    */
   CheckboxIndicatorDataAttributes[CheckboxIndicatorDataAttributes["startingStyle"] = TransitionStatusDataAttributes.startingStyle] = "startingStyle";
   /**

package/checkbox/root/CheckboxRoot.d.mts

@@ -103,7 +103,8 @@ export interface CheckboxRootProps extends NonNativeButtonProps, Omit<BaseUIComp
    */
   uncheckedValue?: string | undefined;
   /**
-   * The value of the selected checkbox.
+   * The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted.
+   * When submitting a form, a checked box submits `value`; with no `value`, it submits the native "on".
    */
   value?: string | undefined;
 }

package/checkbox/root/CheckboxRoot.d.ts

@@ -103,7 +103,8 @@ export interface CheckboxRootProps extends NonNativeButtonProps, Omit<BaseUIComp
    */
   uncheckedValue?: string | undefined;
   /**
-   * The value of the selected checkbox.
+   * The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted.
+   * When submitting a form, a checked box submits `value`; with no `value`, it submits the native "on".
    */
   value?: string | undefined;
 }

package/checkbox/root/CheckboxRoot.js

@@ -16,7 +16,8 @@ var _visuallyHidden = require("@base-ui/utils/visuallyHidden");
 var _owner = require("@base-ui/utils/owner");
 var _getDefaultFormSubmitter = require("@base-ui/utils/getDefaultFormSubmitter");
 var _noop = require("../../internals/noop");
-var _useStateAttributesMapping = require("../utils/useStateAttributesMapping");
+var _getCheckboxStateAttributesMapping = require("../utils/getCheckboxStateAttributesMapping");
+var _dispatchClickWithModifiers = require("../../utils/dispatchClickWithModifiers");
 var _useRenderElement = require("../../internals/useRenderElement");
 var _useBaseUiId = require("../../internals/useBaseUiId");
 var _mergeProps = require("../../merge-props");
@@ -87,25 +88,29 @@ const CheckboxRoot = exports.CheckboxRoot = /*#__PURE__*/React.forwardRef(functi
     getDescriptionProps
   } = (0, _LabelableContext.useLabelableContext)();
   const groupContext = (0, _CheckboxGroupContext.useCheckboxGroupContext)();
-  const parentContext = groupContext?.parent;
-  const isGroupedWithParent = parentContext && groupContext.allValues;
+  const parentContext = groupContext?.allValues === undefined ? undefined : groupContext.parent;
+  const isGroupedWithParent = parentContext !== undefined;
   const disabled = rootDisabled || fieldItemContext.disabled || groupContext?.disabled || disabledProp;
   const name = fieldName ?? nameProp;
   const value = valueProp ?? name;
   const id = (0, _useBaseUiId.useBaseUiId)();
-  const parentId = (0, _useBaseUiId.useBaseUiId)();
-  let inputId = controlId;
+  const generatedInputId = (0, _useBaseUiId.useBaseUiId)();
+  let inputId = idProp || controlId;
   if (isGroupedWithParent) {
-    inputId = parent ? parentId : `${parentContext.id}-${value}`;
-  } else if (idProp) {
-    inputId = idProp;
+    if (parent) {
+      inputId = generatedInputId;
+    } else if (value !== undefined) {
+      inputId = `${parentContext.id}-${value}`;
+    } else {
+      inputId ||= generatedInputId;
+    }
   }
   let groupProps = {};
   if (isGroupedWithParent) {
     if (parent) {
-      groupProps = groupContext.parent.getParentProps();
-    } else if (value) {
-      groupProps = groupContext.parent.getChildProps(value);
+      groupProps = parentContext.getParentProps();
+    } else if (value !== undefined) {
+      groupProps = parentContext.getChildProps(value);
     }
   }
   const {
@@ -115,10 +120,8 @@ const CheckboxRoot = exports.CheckboxRoot = /*#__PURE__*/React.forwardRef(functi
     ...otherGroupProps
   } = groupProps;
   const groupValue = groupContext?.value;
-  const setGroupValue = groupContext?.setValue;
-  const defaultGroupValue = groupContext?.defaultValue;
   const controlRef = React.useRef(null);
-  const controlSourceRef = (0, _useRefWithInit.useRefWithInit)(() => Symbol('checkbox-control'));
+  const controlSourceRef = (0, _useRefWithInit.useRefWithInit)(() => Symbol());
   const hasRegisteredRef = React.useRef(false);
   const {
     getButtonProps,
@@ -129,8 +132,8 @@ const CheckboxRoot = exports.CheckboxRoot = /*#__PURE__*/React.forwardRef(functi
   });
   const validation = groupContext?.validation ?? localValidation;
   const [checked, setCheckedState] = (0, _useControlled.useControlled)({
-    controlled: value && groupValue && !parent ? groupValue.includes(value) : groupChecked,
-    default: value && defaultGroupValue && !parent ? defaultGroupValue.includes(value) : defaultChecked,
+    controlled: value !== undefined && groupValue !== undefined && !parent ? groupValue.includes(value) : groupChecked,
+    default: defaultChecked,
     name: 'Checkbox',
     state: 'checked'
   });
@@ -158,7 +161,13 @@ const CheckboxRoot = exports.CheckboxRoot = /*#__PURE__*/React.forwardRef(functi
   }, [registerControlId, controlSourceRef]);
   (0, _useRegisterFieldControl.useRegisterFieldControl)(controlRef, id, checked, undefined, !groupContext && !disabled, nameProp);
   const inputRef = React.useRef(null);
-  const mergedInputRef = (0, _useMergedRefs.useMergedRefs)(inputRefProp, inputRef, validation.inputRef, validation.registerInput);
+  const registerFieldInput = validation.registerInput;
+  const registeredInputValue = groupContext ? value : undefined;
+  const registerInput = React.useCallback(element => registerFieldInput(element, {
+    controlRef,
+    value: registeredInputValue
+  }), [registerFieldInput, registeredInputValue]);
+  const mergedInputRef = (0, _useMergedRefs.useMergedRefs)(inputRefProp, inputRef, parent ? undefined : registerInput);
   const ariaLabelledBy = (0, _useAriaLabelledBy.useAriaLabelledBy)(ariaLabelledByProp, labelId, inputRef, !nativeButton, inputId ?? undefined);
   (0, _useIsoLayoutEffect.useIsoLayoutEffect)(() => {
     if (inputRef.current) {
@@ -193,7 +202,7 @@ const CheckboxRoot = exports.CheckboxRoot = /*#__PURE__*/React.forwardRef(functi
     type: 'checkbox',
     'aria-hidden': true,
     onChange(event) {
-      // Workaround for https://github.com/facebook/react/issues/9023
+      // Workaround for https://github.com/react/react/issues/9023
       if (event.nativeEvent.defaultPrevented) {
         return;
       }
@@ -212,11 +221,16 @@ const CheckboxRoot = exports.CheckboxRoot = /*#__PURE__*/React.forwardRef(functi
         return;
       }
       setCheckedState(nextChecked);
-      if (value && groupValue && setGroupValue && !parent && !isGroupedWithParent) {
-        const nextGroupValue = nextChecked ? [...groupValue, value] : groupValue.filter(item => item !== value);
-        setGroupValue(nextGroupValue, details);
+      if (value !== undefined && groupContext !== undefined && !parent && !isGroupedWithParent) {
+        const nextGroupValue = nextChecked ? [...groupContext.value, value] : groupContext.value.filter(item => item !== value);
+        groupContext.setValue(nextGroupValue, details);
       }
     },
+    onClick(event) {
+      // The click dispatched from the root's `onClick` is an implementation detail
+      // and must not reach ancestors, which already receive the original click.
+      event.stopPropagation();
+    },
     onFocus() {
       controlRef.current?.focus();
     }
@@ -227,7 +241,7 @@ const CheckboxRoot = exports.CheckboxRoot = /*#__PURE__*/React.forwardRef(functi
     value: (groupContext ? checked && valueProp : valueProp) || ''
   } : _empty.EMPTY_OBJECT, getDescriptionProps, props => validation.getValidationProps(disabled, props));
   React.useEffect(() => {
-    if (!parentContext || !value) {
+    if (!parentContext || value === undefined) {
       return undefined;
     }
     const disabledStates = parentContext.disabledStatesRef.current;
@@ -244,10 +258,10 @@ const CheckboxRoot = exports.CheckboxRoot = /*#__PURE__*/React.forwardRef(functi
     required,
     indeterminate: computedIndeterminate
   }), [fieldState, computedChecked, disabled, readOnly, required, computedIndeterminate]);
-  const stateAttributesMapping = (0, _useStateAttributesMapping.useStateAttributesMapping)(state);
+  const stateAttributesMapping = (0, _getCheckboxStateAttributesMapping.getCheckboxStateAttributesMapping)(state);
   const element = (0, _useRenderElement.useRenderElement)('span', componentProps, {
     state,
-    ref: [buttonRef, controlRef, forwardedRef, groupContext?.registerControlRef],
+    ref: [buttonRef, controlRef, forwardedRef],
     props: [{
       id: nativeButton ? inputId ?? undefined : id,
       role: 'checkbox',
@@ -319,13 +333,7 @@ const CheckboxRoot = exports.CheckboxRoot = /*#__PURE__*/React.forwardRef(functi
         if (!input) {
           return;
         }
-        input.dispatchEvent(new ((0, _owner.ownerWindow)(input).PointerEvent)('click', {
-          bubbles: true,
-          shiftKey: event.shiftKey,
-          ctrlKey: event.ctrlKey,
-          altKey: event.altKey,
-          metaKey: event.metaKey
-        }));
+        (0, _dispatchClickWithModifiers.dispatchClickWithModifiers)(input, event);
       }
     }, elementProps, otherGroupProps, getButtonProps, getDescriptionProps, props => validation.getValidationProps(disabled, props)],
     stateAttributesMapping

package/checkbox/root/CheckboxRoot.mjs

@@ -10,7 +10,8 @@ import { visuallyHidden, visuallyHiddenInput } from '@base-ui/utils/visuallyHidd
 import { ownerWindow } from '@base-ui/utils/owner';
 import { getDefaultFormSubmitter } from '@base-ui/utils/getDefaultFormSubmitter';
 import { NOOP } from "../../internals/noop.mjs";
-import { useStateAttributesMapping } from "../utils/useStateAttributesMapping.mjs";
+import { getCheckboxStateAttributesMapping } from "../utils/getCheckboxStateAttributesMapping.mjs";
+import { dispatchClickWithModifiers } from "../../utils/dispatchClickWithModifiers.mjs";
 import { useRenderElement } from "../../internals/useRenderElement.mjs";
 import { useBaseUiId } from "../../internals/useBaseUiId.mjs";
 import { mergeProps } from "../../merge-props/index.mjs";
@@ -81,25 +82,29 @@ export const CheckboxRoot = /*#__PURE__*/React.forwardRef(function CheckboxRoot(
     getDescriptionProps
   } = useLabelableContext();
   const groupContext = useCheckboxGroupContext();
-  const parentContext = groupContext?.parent;
-  const isGroupedWithParent = parentContext && groupContext.allValues;
+  const parentContext = groupContext?.allValues === undefined ? undefined : groupContext.parent;
+  const isGroupedWithParent = parentContext !== undefined;
   const disabled = rootDisabled || fieldItemContext.disabled || groupContext?.disabled || disabledProp;
   const name = fieldName ?? nameProp;
   const value = valueProp ?? name;
   const id = useBaseUiId();
-  const parentId = useBaseUiId();
-  let inputId = controlId;
+  const generatedInputId = useBaseUiId();
+  let inputId = idProp || controlId;
   if (isGroupedWithParent) {
-    inputId = parent ? parentId : `${parentContext.id}-${value}`;
-  } else if (idProp) {
-    inputId = idProp;
+    if (parent) {
+      inputId = generatedInputId;
+    } else if (value !== undefined) {
+      inputId = `${parentContext.id}-${value}`;
+    } else {
+      inputId ||= generatedInputId;
+    }
   }
   let groupProps = {};
   if (isGroupedWithParent) {
     if (parent) {
-      groupProps = groupContext.parent.getParentProps();
-    } else if (value) {
-      groupProps = groupContext.parent.getChildProps(value);
+      groupProps = parentContext.getParentProps();
+    } else if (value !== undefined) {
+      groupProps = parentContext.getChildProps(value);
     }
   }
   const {
@@ -109,10 +114,8 @@ export const CheckboxRoot = /*#__PURE__*/React.forwardRef(function CheckboxRoot(
     ...otherGroupProps
   } = groupProps;
   const groupValue = groupContext?.value;
-  const setGroupValue = groupContext?.setValue;
-  const defaultGroupValue = groupContext?.defaultValue;
   const controlRef = React.useRef(null);
-  const controlSourceRef = useRefWithInit(() => Symbol('checkbox-control'));
+  const controlSourceRef = useRefWithInit(() => Symbol());
   const hasRegisteredRef = React.useRef(false);
   const {
     getButtonProps,
@@ -123,8 +126,8 @@ export const CheckboxRoot = /*#__PURE__*/React.forwardRef(function CheckboxRoot(
   });
   const validation = groupContext?.validation ?? localValidation;
   const [checked, setCheckedState] = useControlled({
-    controlled: value && groupValue && !parent ? groupValue.includes(value) : groupChecked,
-    default: value && defaultGroupValue && !parent ? defaultGroupValue.includes(value) : defaultChecked,
+    controlled: value !== undefined && groupValue !== undefined && !parent ? groupValue.includes(value) : groupChecked,
+    default: defaultChecked,
     name: 'Checkbox',
     state: 'checked'
   });
@@ -152,7 +155,13 @@ export const CheckboxRoot = /*#__PURE__*/React.forwardRef(function CheckboxRoot(
   }, [registerControlId, controlSourceRef]);
   useRegisterFieldControl(controlRef, id, checked, undefined, !groupContext && !disabled, nameProp);
   const inputRef = React.useRef(null);
-  const mergedInputRef = useMergedRefs(inputRefProp, inputRef, validation.inputRef, validation.registerInput);
+  const registerFieldInput = validation.registerInput;
+  const registeredInputValue = groupContext ? value : undefined;
+  const registerInput = React.useCallback(element => registerFieldInput(element, {
+    controlRef,
+    value: registeredInputValue
+  }), [registerFieldInput, registeredInputValue]);
+  const mergedInputRef = useMergedRefs(inputRefProp, inputRef, parent ? undefined : registerInput);
   const ariaLabelledBy = useAriaLabelledBy(ariaLabelledByProp, labelId, inputRef, !nativeButton, inputId ?? undefined);
   useIsoLayoutEffect(() => {
     if (inputRef.current) {
@@ -187,7 +196,7 @@ export const CheckboxRoot = /*#__PURE__*/React.forwardRef(function CheckboxRoot(
     type: 'checkbox',
     'aria-hidden': true,
     onChange(event) {
-      // Workaround for https://github.com/facebook/react/issues/9023
+      // Workaround for https://github.com/react/react/issues/9023
       if (event.nativeEvent.defaultPrevented) {
         return;
       }
@@ -206,11 +215,16 @@ export const CheckboxRoot = /*#__PURE__*/React.forwardRef(function CheckboxRoot(
         return;
       }
       setCheckedState(nextChecked);
-      if (value && groupValue && setGroupValue && !parent && !isGroupedWithParent) {
-        const nextGroupValue = nextChecked ? [...groupValue, value] : groupValue.filter(item => item !== value);
-        setGroupValue(nextGroupValue, details);
+      if (value !== undefined && groupContext !== undefined && !parent && !isGroupedWithParent) {
+        const nextGroupValue = nextChecked ? [...groupContext.value, value] : groupContext.value.filter(item => item !== value);
+        groupContext.setValue(nextGroupValue, details);
       }
     },
+    onClick(event) {
+      // The click dispatched from the root's `onClick` is an implementation detail
+      // and must not reach ancestors, which already receive the original click.
+      event.stopPropagation();
+    },
     onFocus() {
       controlRef.current?.focus();
     }
@@ -221,7 +235,7 @@ export const CheckboxRoot = /*#__PURE__*/React.forwardRef(function CheckboxRoot(
     value: (groupContext ? checked && valueProp : valueProp) || ''
   } : EMPTY_OBJECT, getDescriptionProps, props => validation.getValidationProps(disabled, props));
   React.useEffect(() => {
-    if (!parentContext || !value) {
+    if (!parentContext || value === undefined) {
       return undefined;
     }
     const disabledStates = parentContext.disabledStatesRef.current;
@@ -238,10 +252,10 @@ export const CheckboxRoot = /*#__PURE__*/React.forwardRef(function CheckboxRoot(
     required,
     indeterminate: computedIndeterminate
   }), [fieldState, computedChecked, disabled, readOnly, required, computedIndeterminate]);
-  const stateAttributesMapping = useStateAttributesMapping(state);
+  const stateAttributesMapping = getCheckboxStateAttributesMapping(state);
   const element = useRenderElement('span', componentProps, {
     state,
-    ref: [buttonRef, controlRef, forwardedRef, groupContext?.registerControlRef],
+    ref: [buttonRef, controlRef, forwardedRef],
     props: [{
       id: nativeButton ? inputId ?? undefined : id,
       role: 'checkbox',
@@ -313,13 +327,7 @@ export const CheckboxRoot = /*#__PURE__*/React.forwardRef(function CheckboxRoot(
         if (!input) {
           return;
         }
-        input.dispatchEvent(new (ownerWindow(input).PointerEvent)('click', {
-          bubbles: true,
-          shiftKey: event.shiftKey,
-          ctrlKey: event.ctrlKey,
-          altKey: event.altKey,
-          metaKey: event.metaKey
-        }));
+        dispatchClickWithModifiers(input, event);
       }
     }, elementProps, otherGroupProps, getButtonProps, getDescriptionProps, props => validation.getValidationProps(disabled, props)],
     stateAttributesMapping

package/checkbox/utils/{useStateAttributesMapping.d.mts → getCheckboxStateAttributesMapping.d.mts}

@@ -1,3 +1,3 @@
 import type { StateAttributesMapping } from "../../internals/getStateAttributesProps.mjs";
 import type { CheckboxRootState } from "../root/CheckboxRoot.mjs";
-export declare function useStateAttributesMapping(state: CheckboxRootState): StateAttributesMapping<CheckboxRootState>;
+export declare function getCheckboxStateAttributesMapping(state: CheckboxRootState): StateAttributesMapping<CheckboxRootState>;

package/checkbox/utils/{useStateAttributesMapping.d.ts → getCheckboxStateAttributesMapping.d.ts}

@@ -1,3 +1,3 @@
 import type { StateAttributesMapping } from "../../internals/getStateAttributesProps.js";
 import type { CheckboxRootState } from "../root/CheckboxRoot.js";
-export declare function useStateAttributesMapping(state: CheckboxRootState): StateAttributesMapping<CheckboxRootState>;
+export declare function getCheckboxStateAttributesMapping(state: CheckboxRootState): StateAttributesMapping<CheckboxRootState>;

package/checkbox/utils/getCheckboxStateAttributesMapping.js

@@ -0,0 +1,26 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getCheckboxStateAttributesMapping = getCheckboxStateAttributesMapping;
+var _constants = require("../../internals/field-constants/constants");
+function getCheckboxStateAttributesMapping(state) {
+  return {
+    checked(value) {
+      if (state.indeterminate) {
+        // `data-indeterminate` is already handled by the `indeterminate` prop.
+        return {};
+      }
+      if (value) {
+        return {
+          'data-checked': ''
+        };
+      }
+      return {
+        'data-unchecked': ''
+      };
+    },
+    ..._constants.fieldValidityMapping
+  };
+}

package/checkbox/utils/{useStateAttributesMapping.mjs → getCheckboxStateAttributesMapping.mjs}

@@ -1,10 +1,6 @@
-'use client';
-
-import * as React from 'react';
-import { CheckboxRootDataAttributes } from "../root/CheckboxRootDataAttributes.mjs";
 import { fieldValidityMapping } from "../../internals/field-constants/constants.mjs";
-export function useStateAttributesMapping(state) {
-  return React.useMemo(() => ({
+export function getCheckboxStateAttributesMapping(state) {
+  return {
     checked(value) {
       if (state.indeterminate) {
         // `data-indeterminate` is already handled by the `indeterminate` prop.
@@ -12,13 +8,13 @@ export function useStateAttributesMapping(state) {
       }
       if (value) {
         return {
-          [CheckboxRootDataAttributes.checked]: ''
+          'data-checked': ''
         };
       }
       return {
-        [CheckboxRootDataAttributes.unchecked]: ''
+        'data-unchecked': ''
       };
     },
     ...fieldValidityMapping
-  }), [state.indeterminate]);
+  };
 }

package/checkbox-group/CheckboxGroup.js

@@ -13,11 +13,11 @@ var _empty = require("@base-ui/utils/empty");
 var _useBaseUiId = require("../internals/useBaseUiId");
 var _useRenderElement = require("../internals/useRenderElement");
 var _CheckboxGroupContext = require("./CheckboxGroupContext");
+var _useFieldValidation = require("../field/root/useFieldValidation");
 var _FieldRootContext = require("../internals/field-root-context/FieldRootContext");
 var _useRegisterFieldControl = require("../internals/field-register-control/useRegisterFieldControl");
 var _LabelableContext = require("../internals/labelable-provider/LabelableContext");
 var _constants = require("../internals/field-constants/constants");
-var _CheckboxRoot = require("../checkbox/root/CheckboxRoot");
 var _useCheckboxGroupParent = require("./useCheckboxGroupParent");
 var _FormContext = require("../internals/form-context/FormContext");
 var _useValueChanged = require("../internals/useValueChanged");
@@ -55,16 +55,15 @@ const CheckboxGroup = exports.CheckboxGroup = /*#__PURE__*/React.forwardRef(func
     getDescriptionProps
   } = (0, _LabelableContext.useLabelableContext)();
   const {
-    clearErrors
+    clearErrors,
+    elementRef
   } = (0, _FormContext.useFormContext)();
   const disabled = fieldDisabled || disabledProp;
-  const defaultValue = React.useMemo(() => {
-    if (externalValue === undefined) {
-      return defaultValueProp ?? [];
-    }
-    return undefined;
-  }, [externalValue, defaultValueProp]);
-  const [value, setValueUnwrapped] = (0, _useControlled.useControlled)({
+  const defaultValue = defaultValueProp ?? _empty.EMPTY_ARRAY;
+
+  // A controlled value can still be `undefined` at runtime even though `useControlled`'s
+  // generic return type says otherwise. Keep the fallback to prevent group consumers from crashing.
+  const [value = _empty.EMPTY_ARRAY, setValueUnwrapped] = (0, _useControlled.useControlled)({
     controlled: externalValue,
     default: defaultValue,
     name: 'CheckboxGroup',
@@ -83,22 +82,34 @@ const CheckboxGroup = exports.CheckboxGroup = /*#__PURE__*/React.forwardRef(func
     onValueChange: setValue
   });
   const id = (0, _useBaseUiId.useBaseUiId)(idProp);
-  const controlRef = React.useRef(null);
-  const registerControlRef = React.useCallback(element => {
-    if (controlRef.current == null && element != null && !element.hasAttribute(_CheckboxRoot.PARENT_CHECKBOX)) {
-      controlRef.current = element;
+  const getInputControl = validation.getInputControl;
+  const controlRef = React.useMemo(() => ({
+    get current() {
+      return getInputControl();
+    }
+  }), [getInputControl]);
+  const getFormValue = (0, _useStableCallback.useStableCallback)(() => {
+    const formElement = elementRef.current;
+    if (!formElement) {
+      return value;
     }
-  }, []);
-  (0, _useRegisterFieldControl.useRegisterFieldControl)(controlRef, id, value, undefined, !!fieldName && !disabled, fieldName);
-  const resolvedValue = value ?? _empty.EMPTY_ARRAY;
-  (0, _useValueChanged.useValueChanged)(resolvedValue, () => {
+    const successfulValues = new Set();
+    for (const [input, registration] of validation.registeredInputs) {
+      if (registration.value !== undefined && input.checked && (0, _useFieldValidation.isEligibleInput)(input, formElement)) {
+        successfulValues.add(registration.value);
+      }
+    }
+    return value.filter(inputValue => successfulValues.has(inputValue));
+  });
+  (0, _useRegisterFieldControl.useRegisterFieldControl)(controlRef, id, value, getFormValue, !!fieldName && !disabled, fieldName);
+  (0, _useValueChanged.useValueChanged)(value, () => {
     if (fieldName) {
       clearErrors(fieldName);
     }
     const initialValue = Array.isArray(validityData.initialValue) ? validityData.initialValue : _empty.EMPTY_ARRAY;
-    setFilled(resolvedValue.length > 0);
-    setDirty(!(0, _areArraysEqual.areArraysEqual)(resolvedValue, initialValue));
-    validation.change(resolvedValue);
+    setFilled(value.length > 0);
+    setDirty(!(0, _areArraysEqual.areArraysEqual)(value, initialValue));
+    validation.change(value);
   });
   const state = {
     ...fieldState,
@@ -107,13 +118,11 @@ const CheckboxGroup = exports.CheckboxGroup = /*#__PURE__*/React.forwardRef(func
   const contextValue = React.useMemo(() => ({
     allValues,
     value,
-    defaultValue,
     setValue,
     parent,
     disabled,
-    validation,
-    registerControlRef
-  }), [allValues, value, defaultValue, setValue, parent, disabled, validation, registerControlRef]);
+    validation
+  }), [allValues, value, setValue, parent, disabled, validation]);
   const element = (0, _useRenderElement.useRenderElement)('div', componentProps, {
     state,
     ref: forwardedRef,

package/checkbox-group/CheckboxGroup.mjs

@@ -7,11 +7,11 @@ import { EMPTY_ARRAY } from '@base-ui/utils/empty';
 import { useBaseUiId } from "../internals/useBaseUiId.mjs";
 import { useRenderElement } from "../internals/useRenderElement.mjs";
 import { CheckboxGroupContext } from "./CheckboxGroupContext.mjs";
+import { isEligibleInput } from "../field/root/useFieldValidation.mjs";
 import { useFieldRootContext } from "../internals/field-root-context/FieldRootContext.mjs";
 import { useRegisterFieldControl } from "../internals/field-register-control/useRegisterFieldControl.mjs";
 import { useLabelableContext } from "../internals/labelable-provider/LabelableContext.mjs";
 import { fieldValidityMapping } from "../internals/field-constants/constants.mjs";
-import { PARENT_CHECKBOX } from "../checkbox/root/CheckboxRoot.mjs";
 import { useCheckboxGroupParent } from "./useCheckboxGroupParent.mjs";
 import { useFormContext } from "../internals/form-context/FormContext.mjs";
 import { useValueChanged } from "../internals/useValueChanged.mjs";
@@ -50,16 +50,15 @@ export const CheckboxGroup = /*#__PURE__*/React.forwardRef(function CheckboxGrou
     getDescriptionProps
   } = useLabelableContext();
   const {
-    clearErrors
+    clearErrors,
+    elementRef
   } = useFormContext();
   const disabled = fieldDisabled || disabledProp;
-  const defaultValue = React.useMemo(() => {
-    if (externalValue === undefined) {
-      return defaultValueProp ?? [];
-    }
-    return undefined;
-  }, [externalValue, defaultValueProp]);
-  const [value, setValueUnwrapped] = useControlled({
+  const defaultValue = defaultValueProp ?? EMPTY_ARRAY;
+
+  // A controlled value can still be `undefined` at runtime even though `useControlled`'s
+  // generic return type says otherwise. Keep the fallback to prevent group consumers from crashing.
+  const [value = EMPTY_ARRAY, setValueUnwrapped] = useControlled({
     controlled: externalValue,
     default: defaultValue,
     name: 'CheckboxGroup',
@@ -78,22 +77,34 @@ export const CheckboxGroup = /*#__PURE__*/React.forwardRef(function CheckboxGrou
     onValueChange: setValue
   });
   const id = useBaseUiId(idProp);
-  const controlRef = React.useRef(null);
-  const registerControlRef = React.useCallback(element => {
-    if (controlRef.current == null && element != null && !element.hasAttribute(PARENT_CHECKBOX)) {
-      controlRef.current = element;
+  const getInputControl = validation.getInputControl;
+  const controlRef = React.useMemo(() => ({
+    get current() {
+      return getInputControl();
+    }
+  }), [getInputControl]);
+  const getFormValue = useStableCallback(() => {
+    const formElement = elementRef.current;
+    if (!formElement) {
+      return value;
     }
-  }, []);
-  useRegisterFieldControl(controlRef, id, value, undefined, !!fieldName && !disabled, fieldName);
-  const resolvedValue = value ?? EMPTY_ARRAY;
-  useValueChanged(resolvedValue, () => {
+    const successfulValues = new Set();
+    for (const [input, registration] of validation.registeredInputs) {
+      if (registration.value !== undefined && input.checked && isEligibleInput(input, formElement)) {
+        successfulValues.add(registration.value);
+      }
+    }
+    return value.filter(inputValue => successfulValues.has(inputValue));
+  });
+  useRegisterFieldControl(controlRef, id, value, getFormValue, !!fieldName && !disabled, fieldName);
+  useValueChanged(value, () => {
     if (fieldName) {
       clearErrors(fieldName);
     }
     const initialValue = Array.isArray(validityData.initialValue) ? validityData.initialValue : EMPTY_ARRAY;
-    setFilled(resolvedValue.length > 0);
-    setDirty(!areArraysEqual(resolvedValue, initialValue));
-    validation.change(resolvedValue);
+    setFilled(value.length > 0);
+    setDirty(!areArraysEqual(value, initialValue));
+    validation.change(value);
   });
   const state = {
     ...fieldState,
@@ -102,13 +113,11 @@ export const CheckboxGroup = /*#__PURE__*/React.forwardRef(function CheckboxGrou
   const contextValue = React.useMemo(() => ({
     allValues,
     value,
-    defaultValue,
     setValue,
     parent,
     disabled,
-    validation,
-    registerControlRef
-  }), [allValues, value, defaultValue, setValue, parent, disabled, validation, registerControlRef]);
+    validation
+  }), [allValues, value, setValue, parent, disabled, validation]);
   const element = useRenderElement('div', componentProps, {
     state,
     ref: forwardedRef,

package/checkbox-group/CheckboxGroupContext.d.mts

@@ -4,15 +4,12 @@ import type { UseCheckboxGroupParentReturnValue } from "./useCheckboxGroupParent
 import type { BaseUIChangeEventDetails } from "../internals/createBaseUIEventDetails.mjs";
 import type { BaseUIEventReasons } from "../internals/reasons.mjs";
 export interface CheckboxGroupContext {
-  value: string[] | undefined;
-  defaultValue: string[] | undefined;
+  value: string[];
   setValue: (value: string[], eventDetails: BaseUIChangeEventDetails<BaseUIEventReasons['none']>) => void;
   allValues: string[] | undefined;
   parent: UseCheckboxGroupParentReturnValue;
   disabled: boolean;
   validation: UseFieldValidationReturnValue;
-  registerControlRef: (element: HTMLButtonElement | null) => void;
 }
 export declare const CheckboxGroupContext: React.Context<CheckboxGroupContext | undefined>;
-export declare function useCheckboxGroupContext(optional: false): CheckboxGroupContext;
-export declare function useCheckboxGroupContext(optional?: true): CheckboxGroupContext | undefined;
+export declare function useCheckboxGroupContext(): CheckboxGroupContext | undefined;

package/checkbox-group/CheckboxGroupContext.d.ts

@@ -4,15 +4,12 @@ import type { UseCheckboxGroupParentReturnValue } from "./useCheckboxGroupParent
 import type { BaseUIChangeEventDetails } from "../internals/createBaseUIEventDetails.js";
 import type { BaseUIEventReasons } from "../internals/reasons.js";
 export interface CheckboxGroupContext {
-  value: string[] | undefined;
-  defaultValue: string[] | undefined;
+  value: string[];
   setValue: (value: string[], eventDetails: BaseUIChangeEventDetails<BaseUIEventReasons['none']>) => void;
   allValues: string[] | undefined;
   parent: UseCheckboxGroupParentReturnValue;
   disabled: boolean;
   validation: UseFieldValidationReturnValue;
-  registerControlRef: (element: HTMLButtonElement | null) => void;
 }
 export declare const CheckboxGroupContext: React.Context<CheckboxGroupContext | undefined>;
-export declare function useCheckboxGroupContext(optional: false): CheckboxGroupContext;
-export declare function useCheckboxGroupContext(optional?: true): CheckboxGroupContext | undefined;
+export declare function useCheckboxGroupContext(): CheckboxGroupContext | undefined;