@base-ui/react 1.2.0 → 1.4.0

package/esm/combobox/positioner/ComboboxPositioner.d.ts

@@ -1,9 +1,11 @@
 import * as React from 'react';
-import { type Side, type Align, useAnchorPositioning } from "../../utils/useAnchorPositioning.js";
+import { type Side, type Align, type UseAnchorPositioningSharedParameters } from "../../utils/useAnchorPositioning.js";
 import type { BaseUIComponentProps } from "../../utils/types.js";
 /**
  * Positions the popup against the trigger.
  * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
 export declare const ComboboxPositioner: React.ForwardRefExoticComponent<Omit<ComboboxPositionerProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface ComboboxPositionerState {
@@ -11,12 +13,24 @@ export interface ComboboxPositionerState {
    * Whether the popup is currently open.
    */
   open: boolean;
+  /**
+   * The side of the anchor the component is placed on.
+   */
   side: Side;
+  /**
+   * The alignment of the component relative to the anchor.
+   */
   align: Align;
+  /**
+   * Whether the anchor element is hidden.
+   */
   anchorHidden: boolean;
+  /**
+   * Whether there are no items to display.
+   */
   empty: boolean;
 }
-export interface ComboboxPositionerProps extends useAnchorPositioning.SharedParameters, BaseUIComponentProps<'div', ComboboxPositioner.State> {}
+export interface ComboboxPositionerProps extends UseAnchorPositioningSharedParameters, BaseUIComponentProps<'div', ComboboxPositionerState> {}
 export declare namespace ComboboxPositioner {
   type State = ComboboxPositionerState;
   type Props = ComboboxPositionerProps;

package/esm/combobox/positioner/ComboboxPositioner.js

@@ -5,21 +5,21 @@ import { useStore } from '@base-ui/utils/store';
 import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
 import { useStableCallback } from '@base-ui/utils/useStableCallback';
 import { inertValue } from '@base-ui/utils/inertValue';
-import { useScrollLock } from '@base-ui/utils/useScrollLock';
 import { useComboboxFloatingContext, useComboboxRootContext, useComboboxDerivedItemsContext } from "../root/ComboboxRootContext.js";
 import { ComboboxPositionerContext } from "./ComboboxPositionerContext.js";
 import { useAnchorPositioning } from "../../utils/useAnchorPositioning.js";
-import { popupStateMapping } from "../../utils/popupStateMapping.js";
 import { useComboboxPortalContext } from "../portal/ComboboxPortalContext.js";
 import { DROPDOWN_COLLISION_AVOIDANCE } from "../../utils/constants.js";
-import { getDisabledMountTransitionStyles } from "../../utils/getDisabledMountTransitionStyles.js";
-import { useRenderElement } from "../../utils/useRenderElement.js";
 import { selectors } from "../store.js";
 import { InternalBackdrop } from "../../utils/InternalBackdrop.js";
+import { usePositioner } from "../../utils/usePositioner.js";
+import { useAnchoredPopupScrollLock } from "../../utils/useAnchoredPopupScrollLock.js";
 
 /**
  * Positions the popup against the trigger.
  * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 export const ComboboxPositioner = /*#__PURE__*/React.forwardRef(function ComboboxPositioner(componentProps, forwardedRef) {
@@ -38,6 +38,7 @@ export const ComboboxPositioner = /*#__PURE__*/React.forwardRef(function Combobo
     sticky = false,
     disableAnchorTracking = false,
     collisionAvoidance = DROPDOWN_COLLISION_AVOIDANCE,
+    style: styleProp,
     ...elementProps
   } = componentProps;
   const store = useComboboxRootContext();
@@ -50,12 +51,14 @@ export const ComboboxPositioner = /*#__PURE__*/React.forwardRef(function Combobo
   const open = useStore(store, selectors.open);
   const mounted = useStore(store, selectors.mounted);
   const openMethod = useStore(store, selectors.openMethod);
+  const positionerElement = useStore(store, selectors.positionerElement);
   const triggerElement = useStore(store, selectors.triggerElement);
   const inputElement = useStore(store, selectors.inputElement);
+  const inputGroupElement = useStore(store, selectors.inputGroupElement);
   const inputInsidePopup = useStore(store, selectors.inputInsidePopup);
   const transitionStatus = useStore(store, selectors.transitionStatus);
   const empty = filteredItems.length === 0;
-  const resolvedAnchor = anchor ?? (inputInsidePopup ? triggerElement : inputElement);
+  const resolvedAnchor = anchor ?? (inputInsidePopup ? triggerElement : inputGroupElement ?? inputElement);
   const positioning = useAnchorPositioning({
     anchor: resolvedAnchor,
     floatingRootContext,
@@ -74,20 +77,7 @@ export const ComboboxPositioner = /*#__PURE__*/React.forwardRef(function Combobo
     collisionAvoidance,
     lazyFlip: true
   });
-  useScrollLock(open && modal && openMethod !== 'touch', triggerElement);
-  const defaultProps = React.useMemo(() => {
-    const style = {
-      ...positioning.positionerStyles
-    };
-    if (!open) {
-      style.pointerEvents = 'none';
-    }
-    return {
-      role: 'presentation',
-      hidden: !mounted,
-      style
-    };
-  }, [open, mounted, positioning.positionerStyles]);
+  useAnchoredPopupScrollLock(open && modal, openMethod === 'touch', positionerElement, triggerElement);
   const state = {
     open,
     side: positioning.side,
@@ -98,29 +88,22 @@ export const ComboboxPositioner = /*#__PURE__*/React.forwardRef(function Combobo
   useIsoLayoutEffect(() => {
     store.set('popupSide', positioning.side);
   }, [store, positioning.side]);
-  const contextValue = React.useMemo(() => ({
-    side: positioning.side,
-    align: positioning.align,
-    arrowRef: positioning.arrowRef,
-    arrowUncentered: positioning.arrowUncentered,
-    arrowStyles: positioning.arrowStyles,
-    anchorHidden: positioning.anchorHidden,
-    isPositioned: positioning.isPositioned
-  }), [positioning.side, positioning.align, positioning.arrowRef, positioning.arrowUncentered, positioning.arrowStyles, positioning.anchorHidden, positioning.isPositioned]);
   const setPositionerElement = useStableCallback(element => {
     store.set('positionerElement', element);
   });
-  const element = useRenderElement('div', componentProps, {
-    state,
-    ref: [forwardedRef, setPositionerElement],
-    props: [defaultProps, getDisabledMountTransitionStyles(transitionStatus), elementProps],
-    stateAttributesMapping: popupStateMapping
+  const element = usePositioner(componentProps, state, {
+    styles: positioning.positionerStyles,
+    transitionStatus,
+    props: elementProps,
+    refs: [forwardedRef, setPositionerElement],
+    hidden: !mounted,
+    inert: !open
   });
   return /*#__PURE__*/_jsxs(ComboboxPositionerContext.Provider, {
-    value: contextValue,
+    value: positioning,
     children: [mounted && modal && /*#__PURE__*/_jsx(InternalBackdrop, {
       inert: inertValue(!open),
-      cutout: inputElement ?? triggerElement
+      cutout: inputGroupElement ?? inputElement ?? triggerElement
     }), element]
   });
 });

package/esm/combobox/positioner/ComboboxPositionerContext.d.ts

@@ -1,14 +1,6 @@
 import * as React from 'react';
-import type { Side, Align } from "../../utils/useAnchorPositioning.js";
-export interface ComboboxPositionerContext {
-  side: Side;
-  align: Align;
-  arrowRef: React.RefObject<Element | null>;
-  arrowUncentered: boolean;
-  arrowStyles: React.CSSProperties;
-  anchorHidden: boolean;
-  isPositioned: boolean;
-}
+import type { UseAnchorPositioningReturnValue } from "../../utils/useAnchorPositioning.js";
+export type ComboboxPositionerContext = Pick<UseAnchorPositioningReturnValue, 'side' | 'align' | 'arrowRef' | 'arrowUncentered' | 'arrowStyles' | 'anchorHidden' | 'isPositioned'>;
 export declare const ComboboxPositionerContext: React.Context<ComboboxPositionerContext | undefined>;
 export declare function useComboboxPositionerContext(optional?: false): ComboboxPositionerContext;
 export declare function useComboboxPositionerContext(optional: true): ComboboxPositionerContext | undefined;

package/esm/combobox/root/AriaCombobox.d.ts

@@ -19,6 +19,11 @@ interface ComboboxRootProps<ItemValue> {
    * Identifies the field when a form is submitted.
    */
   name?: string | undefined;
+  /**
+   * Identifies the form that owns the internal input.
+   * Useful when the combobox is rendered outside the form.
+   */
+  form?: string | undefined;
   /**
    * The id of the component.
    */
@@ -69,7 +74,7 @@ interface ComboboxRootProps<ItemValue> {
    * - `'always'`: highlight the first item as soon as the list opens.
    * @default false
    */
-  autoHighlight?: (boolean | 'always') | undefined;
+  autoHighlight?: boolean | 'always' | undefined;
   /**
    * Whether the highlighted item should be preserved when the pointer leaves the list.
    * @default false
@@ -132,17 +137,17 @@ interface ComboboxRootProps<ItemValue> {
    * The items to be displayed in the list.
    * Can be either a flat array of items or an array of groups with items.
    */
-  items?: (readonly any[] | readonly Group<any>[]) | undefined;
+  items?: readonly any[] | readonly Group<any>[] | undefined;
   /**
    * Filtered items to display in the list.
    * When provided, the list will use these items instead of filtering the `items` prop internally.
    * Use when you want to control filtering logic externally with the `useFilter()` hook.
    */
-  filteredItems?: (readonly any[] | readonly Group<any>[]) | undefined;
+  filteredItems?: readonly any[] | readonly Group<any>[] | undefined;
   /**
    * Filter function used to match items vs input query.
    */
-  filter?: (null | ((itemValue: ItemValue, query: string, itemToString?: (itemValue: ItemValue) => string) => boolean)) | undefined;
+  filter?: null | ((itemValue: ItemValue, query: string, itemToString?: (itemValue: ItemValue) => string) => boolean) | undefined;
   /**
    * When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for display in the input.
    * If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop.
@@ -188,7 +193,7 @@ interface ComboboxRootProps<ItemValue> {
    * - `none`: items are static (not filtered), and the input value will not change based on the active item.
    * @default 'list'
    */
-  autoComplete?: ('list' | 'both' | 'inline' | 'none') | undefined;
+  autoComplete?: 'list' | 'both' | 'inline' | 'none' | undefined;
   /**
    * Provides a hint to the browser for autofill on the hidden input element.
    * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete
@@ -209,6 +214,7 @@ interface ComboboxRootProps<ItemValue> {
    */
   fillInputOnItemPress?: boolean | undefined;
 }
+export interface AriaComboboxState {}
 export type AriaComboboxProps<Value, Mode extends SelectionMode = 'none'> = ComboboxRootProps<Value> & {
   /**
    * How the combobox should remember the selected value.
@@ -227,7 +233,7 @@ export type AriaComboboxProps<Value, Mode extends SelectionMode = 'none'> = Comb
    *
    * To render a controlled combobox, use the `selectedValue` prop instead.
    */
-  defaultSelectedValue?: (ComboboxItemValueType<Value, Mode> | null) | undefined;
+  defaultSelectedValue?: ComboboxItemValueType<Value, Mode> | null | undefined;
   /**
    * Callback fired when the selected value of the combobox changes.
    */
@@ -235,7 +241,7 @@ export type AriaComboboxProps<Value, Mode extends SelectionMode = 'none'> = Comb
 };
 export declare namespace AriaCombobox {
   type Props<Value, Mode extends SelectionMode = 'none'> = AriaComboboxProps<Value, Mode>;
-  interface State {}
+  type State = AriaComboboxState;
   interface Actions {
     unmount: () => void;
   }
@@ -243,7 +249,7 @@ export declare namespace AriaCombobox {
   type HighlightEventDetails = BaseUIGenericEventDetails<HighlightEventReason, {
     index: number;
   }>;
-  type ChangeEventReason = typeof REASONS.triggerPress | typeof REASONS.outsidePress | typeof REASONS.itemPress | typeof REASONS.escapeKey | typeof REASONS.listNavigation | typeof REASONS.focusOut | typeof REASONS.inputChange | typeof REASONS.inputClear | typeof REASONS.clearPress | typeof REASONS.chipRemovePress | typeof REASONS.none;
+  type ChangeEventReason = typeof REASONS.triggerPress | typeof REASONS.outsidePress | typeof REASONS.itemPress | typeof REASONS.closePress | typeof REASONS.escapeKey | typeof REASONS.listNavigation | typeof REASONS.focusOut | typeof REASONS.inputChange | typeof REASONS.inputClear | typeof REASONS.clearPress | typeof REASONS.chipRemovePress | typeof REASONS.none;
   type ChangeEventDetails = BaseUIChangeEventDetails<ChangeEventReason>;
 }
 export {};

package/esm/combobox/root/AriaCombobox.js

@@ -6,10 +6,10 @@ import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
 import { useOnFirstRender } from '@base-ui/utils/useOnFirstRender';
 import { useStableCallback } from '@base-ui/utils/useStableCallback';
 import { useMergedRefs } from '@base-ui/utils/useMergedRefs';
+import { useValueAsRef } from '@base-ui/utils/useValueAsRef';
 import { visuallyHidden, visuallyHiddenInput } from '@base-ui/utils/visuallyHidden';
 import { useRefWithInit } from '@base-ui/utils/useRefWithInit';
 import { Store, useStore } from '@base-ui/utils/store';
-import { useValueAsRef } from '@base-ui/utils/useValueAsRef';
 import { useDismiss, useFloatingRootContext, useInteractions, useListNavigation, useClick } from "../../floating-ui-react/index.js";
 import { contains, getTarget } from "../../floating-ui-react/utils.js";
 import { createChangeEventDetails, createGenericEventDetails } from "../../utils/createBaseUIEventDetails.js";
@@ -18,7 +18,7 @@ import { ComboboxFloatingContext, ComboboxDerivedItemsContext, ComboboxRootConte
 import { selectors } from "../store.js";
 import { useOpenChangeComplete } from "../../utils/useOpenChangeComplete.js";
 import { useFieldRootContext } from "../../field/root/FieldRootContext.js";
-import { useField } from "../../field/useField.js";
+import { useRegisterFieldControl } from "../../field/root/useRegisterFieldControl.js";
 import { useFormContext } from "../../form/FormContext.js";
 import { useLabelableId } from "../../labelable-provider/useLabelableId.js";
 import { createCollatorItemFilter, createSingleSelectionCollatorFilter } from "./utils/index.js";
@@ -45,9 +45,12 @@ export function AriaCombobox(props) {
     onSelectedValueChange,
     defaultInputValue: defaultInputValueProp,
     inputValue: inputValueProp,
+    open: openProp,
+    defaultOpen = false,
     selectionMode = 'none',
     onItemHighlighted: onItemHighlightedProp,
     name: nameProp,
+    form,
     disabled: disabledProp = false,
     readOnly = false,
     required = false,
@@ -101,6 +104,8 @@ export function AriaCombobox(props) {
   const labelsRef = React.useRef([]);
   const popupRef = React.useRef(null);
   const inputRef = React.useRef(null);
+  const startDismissRef = React.useRef(null);
+  const endDismissRef = React.useRef(null);
   const emptyRef = React.useRef(null);
   const keyboardActiveRef = React.useRef(true);
   const hadInputClearRef = React.useRef(false);
@@ -171,8 +176,8 @@ export function AriaCombobox(props) {
     state: 'inputValue'
   });
   const [open, setOpenUnwrapped] = useControlled({
-    controlled: props.open,
-    default: props.defaultOpen,
+    controlled: openProp,
+    default: defaultOpen,
     name: 'Combobox',
     state: 'open'
   });
@@ -253,6 +258,7 @@ export function AriaCombobox(props) {
   }, [filteredItems, isGrouped]);
   const store = useRefWithInit(() => new Store({
     id,
+    labelId: undefined,
     selectedValue,
     open,
     filter,
@@ -264,6 +270,8 @@ export function AriaCombobox(props) {
     popupRef,
     emptyRef,
     inputRef,
+    startDismissRef,
+    endDismissRef,
     keyboardActiveRef,
     chipsContainerRef,
     clearRef,
@@ -271,6 +279,7 @@ export function AriaCombobox(props) {
     allValuesRef,
     selectionEventRef,
     name,
+    form,
     disabled,
     readOnly,
     required,
@@ -297,6 +306,7 @@ export function AriaCombobox(props) {
     listElement: null,
     triggerElement: null,
     inputElement: null,
+    inputGroupElement: null,
     popupSide: null,
     openMethod: null,
     inputInsidePopup: true,
@@ -330,6 +340,7 @@ export function AriaCombobox(props) {
   const listElement = useStore(store, selectors.listElement);
   const triggerElement = useStore(store, selectors.triggerElement);
   const inputElement = useStore(store, selectors.inputElement);
+  const inputGroupElement = useStore(store, selectors.inputGroupElement);
   const inline = useStore(store, selectors.inline);
   const inputInsidePopup = useStore(store, selectors.inputInsidePopup);
   const triggerRef = useValueAsRef(triggerElement);
@@ -340,16 +351,13 @@ export function AriaCombobox(props) {
   } = useTransitionStatus(open);
   const {
     openMethod,
-    triggerProps,
-    reset: resetOpenInteractionType
+    triggerProps
   } = useOpenInteractionType(open);
-  useField({
+  const getFieldValue = useStableCallback(() => fieldStringValue);
+  useRegisterFieldControl(inputInsidePopup ? triggerRef : inputRef, {
     id,
-    name,
-    commit: validation.commit,
     value: fieldRawValue,
-    controlRef: inputInsidePopup ? triggerRef : inputRef,
-    getValue: () => fieldStringValue
+    getValue: getFieldValue
   });
   const forceMount = useStableCallback(() => {
     if (items) {
@@ -530,16 +538,15 @@ export function AriaCombobox(props) {
     if (!store.state.submitOnItemClick) {
       return;
     }
-    const form = store.state.inputElement?.form;
-    if (form && typeof form.requestSubmit === 'function') {
-      form.requestSubmit();
+    const formElement = validation.inputRef.current?.form ?? store.state.inputElement?.form;
+    if (formElement && typeof formElement.requestSubmit === 'function') {
+      formElement.requestSubmit();
     }
   });
   const handleUnmount = useStableCallback(() => {
     setMounted(false);
     onOpenChangeComplete?.(false);
     setQueryChangedAfterOpen(false);
-    resetOpenInteractionType();
     setCloseQuery(null);
     if (selectionMode === 'none') {
       setIndices({
@@ -760,8 +767,11 @@ export function AriaCombobox(props) {
   }
   const role = React.useMemo(() => {
     const isPlainInput = inputElement?.tagName === 'INPUT';
-    const shouldApplyAria = isPlainInput || open;
-    const reference = isPlainInput ? {
+    // During SSR and initial hydration, the input ref is not available yet.
+    // Assume an input-like control so combobox ARIA attributes are present.
+    const shouldTreatAsInput = inputElement == null || isPlainInput;
+    const shouldApplyAria = shouldTreatAsInput || open;
+    const reference = shouldTreatAsInput ? {
       autoComplete: 'off',
       spellCheck: 'false',
       autoCorrect: 'off',
@@ -785,9 +795,9 @@ export function AriaCombobox(props) {
     enabled: !readOnly && !disabled && openOnInputClick,
     event: 'mousedown-only',
     toggle: false,
-    // Apply a small delay for touch to let iOS viewport centering settle.
+    // Apply a small delay for touch to let mobile viewport/keyboard positioning settle.
     // This avoids top-bottom flip flickers if the preferred position is "top" when first tapping.
-    touchOpenDelay: inputInsidePopup ? 0 : 50,
+    touchOpenDelay: inputInsidePopup ? 0 : 100,
     reason: REASONS.inputPress
   });
   const dismiss = useDismiss(floatingRootContext, {
@@ -803,7 +813,7 @@ export function AriaCombobox(props) {
     bubbles: inline ? true : undefined,
     outsidePress(event) {
       const target = getTarget(event);
-      return !contains(triggerElement, target) && !contains(clearRef.current, target) && !contains(chipsContainerRef.current, target);
+      return !contains(triggerElement, target) && !contains(clearRef.current, target) && !contains(chipsContainerRef.current, target) && !contains(inputGroupElement, target);
     }
   });
   const listNavigation = useListNavigation(floatingRootContext, {
@@ -880,6 +890,7 @@ export function AriaCombobox(props) {
       getItemProps,
       selectionMode,
       name,
+      form,
       disabled,
       readOnly,
       required,
@@ -896,7 +907,7 @@ export function AriaCombobox(props) {
       hasInputValue,
       requestSubmit
     });
-  }, [store, id, selectedValue, open, mounted, transitionStatus, items, getFloatingProps, getReferenceProps, getItemProps, openMethod, triggerProps, selectionMode, name, disabled, readOnly, required, validation, grid, isGrouped, virtualized, onOpenChangeComplete, openOnInputClick, itemToStringLabel, modal, isItemEqualToValue, submitOnItemClick, hasInputValue, inlineProp, requestSubmit, autoHighlightMode]);
+  }, [store, id, selectedValue, open, mounted, transitionStatus, items, getFloatingProps, getReferenceProps, getItemProps, openMethod, triggerProps, selectionMode, name, disabled, readOnly, required, validation, grid, isGrouped, virtualized, onOpenChangeComplete, openOnInputClick, itemToStringLabel, modal, isItemEqualToValue, submitOnItemClick, hasInputValue, inlineProp, requestSubmit, autoHighlightMode, form]);
   const hiddenInputRef = useMergedRefs(inputRefProp, validation.inputRef);
   const itemsContextValue = React.useMemo(() => ({
     query,
@@ -920,11 +931,12 @@ export function AriaCombobox(props) {
       const currentSerializedValue = stringifyAsValue(value, itemToStringValue);
       return /*#__PURE__*/_jsx("input", {
         type: "hidden",
+        form: form,
         name: name,
         value: currentSerializedValue
       }, currentSerializedValue);
     });
-  }, [multiple, selectedValue, name, itemToStringValue]);
+  }, [multiple, selectedValue, form, name, itemToStringValue]);
   const children = /*#__PURE__*/_jsxs(React.Fragment, {
     children: [props.children, /*#__PURE__*/_jsx("input", {
       ...validation.getInputValidationProps({
@@ -942,7 +954,7 @@ export function AriaCombobox(props) {
           if (event.nativeEvent.defaultPrevented) {
             return;
           }
-          const nextValue = event.target.value;
+          const nextValue = event.currentTarget.value;
           const details = createChangeEventDetails(REASONS.none, event.nativeEvent);
           function handleChange() {
             // Browser autofill only writes a single scalar value.
@@ -958,8 +970,15 @@ export function AriaCombobox(props) {
               return;
             }
             const matchingValue = valuesRef.current.find(v => {
-              const candidate = stringifyAsValue(v, itemToStringValue);
-              if (candidate.toLowerCase() === nextValue.toLowerCase()) {
+              // Try matching by value first (e.g., "US" for country code)
+              const candidateValue = stringifyAsValue(v, itemToStringValue);
+              if (candidateValue.toLowerCase() === nextValue.toLowerCase()) {
+                return true;
+              }
+              // Also try matching by label for browser autofill compatibility
+              // (browsers autofill with displayed text like "United States", not the underlying value)
+              const candidateLabel = stringifyAsLabel(v, itemToStringLabel);
+              if (candidateLabel.toLowerCase() === nextValue.toLowerCase()) {
                 return true;
               }
               return false;
@@ -981,6 +1000,7 @@ export function AriaCombobox(props) {
         }
       }),
       id: id && hiddenInputName == null ? `${id}-hidden-input` : undefined,
+      form: form,
       name: hiddenInputName,
       autoComplete: formAutoComplete,
       disabled: disabled,
@@ -990,7 +1010,8 @@ export function AriaCombobox(props) {
       ref: hiddenInputRef,
       style: hiddenInputName ? visuallyHiddenInput : visuallyHidden,
       tabIndex: -1,
-      "aria-hidden": true
+      "aria-hidden": true,
+      suppressHydrationWarning: true
     }), hiddenInputs]
   });
   return /*#__PURE__*/_jsx(ComboboxRootContext.Provider, {

package/esm/combobox/root/ComboboxRoot.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { AriaCombobox } from "./AriaCombobox.js";
+import { AriaCombobox, type AriaComboboxState } from "./AriaCombobox.js";
 /**
  * Groups all parts of the combobox.
  * Doesn't render its own HTML element.
@@ -51,7 +51,7 @@ export type ComboboxRootProps<Value, Multiple extends boolean | undefined = fals
    *
    * To render a controlled combobox, use the `value` prop instead.
    */
-  defaultValue?: (ComboboxValueType<Value, Multiple> | null) | undefined;
+  defaultValue?: ComboboxValueType<Value, Multiple> | null | undefined;
   /**
    * A ref to imperative actions.
    * - `unmount`: When specified, the combobox will not be unmounted when closed.
@@ -79,13 +79,13 @@ export type ComboboxRootProps<Value, Multiple extends boolean | undefined = fals
   /**
    * The selected value of the combobox. Use when controlled.
    */
-  value?: (ComboboxValueType<Value, Multiple> | null) | undefined;
+  value?: ComboboxValueType<Value, Multiple> | null | undefined;
   /**
    * Event handler called when the selected value of the combobox changes.
    */
   onValueChange?: ((value: ComboboxValueType<Value, Multiple> | (Multiple extends true ? never : null), eventDetails: ComboboxRoot.ChangeEventDetails) => void) | undefined;
 };
-export type ComboboxRootState = AriaCombobox.State;
+export interface ComboboxRootState extends AriaComboboxState {}
 export type ComboboxRootActions = AriaCombobox.Actions;
 export type ComboboxRootChangeEventReason = AriaCombobox.ChangeEventReason;
 export type ComboboxRootChangeEventDetails = AriaCombobox.ChangeEventDetails;

package/esm/combobox/root/utils/useFilter.d.ts

@@ -6,8 +6,17 @@ export interface UseFilterOptions extends Intl.CollatorOptions {
   locale?: Intl.LocalesArgument | undefined;
 }
 export interface Filter {
+  /**
+   * Returns whether the item matches the query anywhere.
+   */
   contains: <Item>(item: Item, query: string, itemToString?: (item: Item) => string) => boolean;
+  /**
+   * Returns whether the item starts with the query.
+   */
   startsWith: <Item>(item: Item, query: string, itemToString?: (item: Item) => string) => boolean;
+  /**
+   * Returns whether the item ends with the query.
+   */
   endsWith: <Item>(item: Item, query: string, itemToString?: (item: Item) => string) => boolean;
 }
 declare function getFilter(options?: UseFilterOptions): Filter;

package/esm/combobox/row/ComboboxRow.d.ts

@@ -4,10 +4,12 @@ import { BaseUIComponentProps } from "../../utils/types.js";
  * Displays a single row of items in a grid list.
  * Enable `grid` on the root component to turn the listbox into a grid.
  * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
 export declare const ComboboxRow: React.ForwardRefExoticComponent<Omit<ComboboxRowProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface ComboboxRowState {}
-export interface ComboboxRowProps extends BaseUIComponentProps<'div', ComboboxRow.State> {}
+export interface ComboboxRowProps extends BaseUIComponentProps<'div', ComboboxRowState> {}
 export declare namespace ComboboxRow {
   type State = ComboboxRowState;
   type Props = ComboboxRowProps;

package/esm/combobox/row/ComboboxRow.js

@@ -8,12 +8,15 @@ import { ComboboxRowContext } from "./ComboboxRowContext.js";
  * Displays a single row of items in a grid list.
  * Enable `grid` on the root component to turn the listbox into a grid.
  * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
 import { jsx as _jsx } from "react/jsx-runtime";
 export const ComboboxRow = /*#__PURE__*/React.forwardRef(function ComboboxRow(componentProps, forwardedRef) {
   const {
     render,
     className,
+    style,
     ...elementProps
   } = componentProps;
   const element = useRenderElement('div', componentProps, {

package/esm/combobox/status/ComboboxStatus.d.ts

@@ -3,11 +3,17 @@ import { BaseUIComponentProps } from "../../utils/types.js";
 /**
  * Displays a status message whose content changes are announced politely to screen readers.
  * Useful for conveying the status of an asynchronously loaded list.
+ * This component's root element must remain mounted in the DOM to announce
+ * changes consistently across screen readers. Avoid hiding or removing the
+ * component itself with `display: none`, `hidden`, `aria-hidden`, or conditional
+ * rendering. Prefer updating or conditionally rendering its children instead.
  * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
 export declare const ComboboxStatus: React.ForwardRefExoticComponent<Omit<ComboboxStatusProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface ComboboxStatusState {}
-export interface ComboboxStatusProps extends BaseUIComponentProps<'div', ComboboxStatus.State> {}
+export interface ComboboxStatusProps extends BaseUIComponentProps<'div', ComboboxStatusState> {}
 export declare namespace ComboboxStatus {
   type State = ComboboxStatusState;
   type Props = ComboboxStatusProps;

package/esm/combobox/status/ComboboxStatus.js

@@ -2,21 +2,32 @@
 
 import * as React from 'react';
 import { useRenderElement } from "../../utils/useRenderElement.js";
+import { useInitialLiveRegionTextMutation } from "../utils/useInitialLiveRegionTextMutation.js";
 
 /**
  * Displays a status message whose content changes are announced politely to screen readers.
  * Useful for conveying the status of an asynchronously loaded list.
+ * This component's root element must remain mounted in the DOM to announce
+ * changes consistently across screen readers. Avoid hiding or removing the
+ * component itself with `display: none`, `hidden`, `aria-hidden`, or conditional
+ * rendering. Prefer updating or conditionally rendering its children instead.
  * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
  */
 export const ComboboxStatus = /*#__PURE__*/React.forwardRef(function ComboboxStatus(componentProps, forwardedRef) {
   const {
     render,
     className,
+    style,
+    children: childrenProp,
     ...elementProps
   } = componentProps;
+  const statusRef = useInitialLiveRegionTextMutation();
   return useRenderElement('div', componentProps, {
-    ref: forwardedRef,
+    ref: [forwardedRef, statusRef],
     props: [{
+      children: childrenProp,
       role: 'status',
       'aria-live': 'polite',
       'aria-atomic': true