@base-ui/react 1.1.0 → 1.2.0

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

@@ -5,11 +5,11 @@ import { Group } from "../../utils/resolveValueLabel.js";
 /**
  * @internal
  */
-export declare function AriaCombobox<Value, Mode extends SelectionMode = 'none'>(props: Omit<ComboboxRootConditionalProps<Value, Mode>, 'items'> & {
+export declare function AriaCombobox<Value, Mode extends SelectionMode = 'none'>(props: Omit<AriaComboboxProps<Value, Mode>, 'items'> & {
   items: readonly Group<any>[];
 }): React.JSX.Element;
-export declare function AriaCombobox<Value, Mode extends SelectionMode = 'none'>(props: Omit<ComboboxRootConditionalProps<Value, Mode>, 'items'> & {
-  items?: readonly any[];
+export declare function AriaCombobox<Value, Mode extends SelectionMode = 'none'>(props: Omit<AriaComboboxProps<Value, Mode>, 'items'> & {
+  items?: readonly any[] | undefined;
 }): React.JSX.Element;
 type SelectionMode = 'single' | 'multiple' | 'none';
 type ComboboxItemValueType<ItemValue, Mode extends SelectionMode> = Mode extends 'multiple' ? ItemValue[] : ItemValue;
@@ -18,50 +18,50 @@ interface ComboboxRootProps<ItemValue> {
   /**
    * Identifies the field when a form is submitted.
    */
-  name?: string;
+  name?: string | undefined;
   /**
    * The id of the component.
    */
-  id?: string;
+  id?: string | undefined;
   /**
    * Whether the user must choose a value before submitting a form.
    * @default false
    */
-  required?: boolean;
+  required?: boolean | undefined;
   /**
    * Whether the user should be unable to choose a different option from the popup.
    * @default false
    */
-  readOnly?: boolean;
+  readOnly?: boolean | undefined;
   /**
    * Whether the component should ignore user interaction.
    * @default false
    */
-  disabled?: boolean;
+  disabled?: boolean | undefined;
   /**
    * Whether the popup is initially open.
    *
    * To render a controlled popup, use the `open` prop instead.
    * @default false
    */
-  defaultOpen?: boolean;
+  defaultOpen?: boolean | undefined;
   /**
    * Whether the popup is currently open. Use when controlled.
    */
-  open?: boolean;
+  open?: boolean | undefined;
   /**
    * Event handler called when the popup is opened or closed.
    */
-  onOpenChange?: (open: boolean, eventDetails: AriaCombobox.ChangeEventDetails) => void;
+  onOpenChange?: ((open: boolean, eventDetails: AriaCombobox.ChangeEventDetails) => void) | undefined;
   /**
    * Event handler called after any animations complete when the popup is opened or closed.
    */
-  onOpenChangeComplete?: (open: boolean) => void;
+  onOpenChangeComplete?: ((open: boolean) => void) | undefined;
   /**
    * Whether the popup opens when clicking the input.
    * @default true
    */
-  openOnInputClick?: boolean;
+  openOnInputClick?: boolean | undefined;
   /**
    * Whether the first matching item is highlighted automatically.
    * - `false`: do not highlight automatically.
@@ -69,46 +69,46 @@ interface ComboboxRootProps<ItemValue> {
    * - `'always'`: highlight the first item as soon as the list opens.
    * @default false
    */
-  autoHighlight?: boolean | 'always';
+  autoHighlight?: (boolean | 'always') | undefined;
   /**
    * Whether the highlighted item should be preserved when the pointer leaves the list.
    * @default false
    */
-  keepHighlight?: boolean;
+  keepHighlight?: boolean | undefined;
   /**
    * Whether moving the pointer over items should highlight them.
    * Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.
    * @default true
    */
-  highlightItemOnHover?: boolean;
+  highlightItemOnHover?: boolean | undefined;
   /**
    * Whether to loop keyboard focus back to the input when the end of the list is reached while using the arrow keys. The first item can then be reached by pressing <kbd>ArrowDown</kbd> again from the input, or the last item can be reached by pressing <kbd>ArrowUp</kbd> from the input.
    * The input is always included in the focus loop per [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
    * When disabled, focus does not move when on the last element and the user presses <kbd>ArrowDown</kbd>, or when on the first element and the user presses <kbd>ArrowUp</kbd>.
    * @default true
    */
-  loopFocus?: boolean;
+  loopFocus?: boolean | undefined;
   /**
    * The input value of the combobox. Use when controlled.
    */
-  inputValue?: React.ComponentProps<'input'>['value'];
+  inputValue?: React.ComponentProps<'input'>['value'] | undefined;
   /**
    * Callback fired when the input value of the combobox changes.
    */
-  onInputValueChange?: (value: string, eventDetails: AriaCombobox.ChangeEventDetails) => void;
+  onInputValueChange?: ((value: string, eventDetails: AriaCombobox.ChangeEventDetails) => void) | undefined;
   /**
    * The uncontrolled input value when initially rendered.
    *
    * To render a controlled input, use the `inputValue` prop instead.
    */
-  defaultInputValue?: React.ComponentProps<'input'>['defaultValue'];
+  defaultInputValue?: React.ComponentProps<'input'>['defaultValue'] | undefined;
   /**
    * A ref to imperative actions.
    * - `unmount`: When specified, the combobox will not be unmounted when closed.
    * Instead, the `unmount` function must be called to unmount the combobox manually.
    * Useful when the combobox's animation is controlled by an external library.
    */
-  actionsRef?: React.RefObject<AriaCombobox.Actions | null>;
+  actionsRef?: React.RefObject<AriaCombobox.Actions | null> | undefined;
   /**
    * Callback fired when an item is highlighted or unhighlighted.
    * Receives the highlighted item value (or `undefined` if no item is highlighted) and event details with a `reason` property describing why the highlight changed.
@@ -117,69 +117,69 @@ interface ComboboxRootProps<ItemValue> {
    * - `'pointer'`: the highlight changed due to pointer hovering.
    * - `'none'`: the highlight changed programmatically.
    */
-  onItemHighlighted?: (itemValue: ItemValue | undefined, eventDetails: AriaCombobox.HighlightEventDetails) => void;
+  onItemHighlighted?: ((itemValue: ItemValue | undefined, eventDetails: AriaCombobox.HighlightEventDetails) => void) | undefined;
   /**
    * A ref to the hidden input element.
    */
-  inputRef?: React.Ref<HTMLInputElement>;
+  inputRef?: React.Ref<HTMLInputElement> | undefined;
   /**
    * Whether list items are presented in a grid layout.
    * When enabled, arrow keys navigate across rows and columns inferred from DOM rows.
    * @default false
    */
-  grid?: boolean;
+  grid?: boolean | undefined;
   /**
    * 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>[];
+  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>[];
+  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);
+  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.
    */
-  itemToStringLabel?: (itemValue: ItemValue) => string;
+  itemToStringLabel?: ((itemValue: ItemValue) => string) | undefined;
   /**
    * When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for form submission.
    * If the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop.
    */
-  itemToStringValue?: (itemValue: ItemValue) => string;
+  itemToStringValue?: ((itemValue: ItemValue) => string) | undefined;
   /**
    * Custom comparison logic used to determine if a combobox item value matches the current selected value. Useful when item values are objects without matching referentially.
    * Defaults to `Object.is` comparison.
    */
-  isItemEqualToValue?: (itemValue: ItemValue, selectedValue: ItemValue) => boolean;
+  isItemEqualToValue?: ((itemValue: ItemValue, value: ItemValue) => boolean) | undefined;
   /**
    * Whether the items are being externally virtualized.
    * @default false
    */
-  virtualized?: boolean;
+  virtualized?: boolean | undefined;
   /**
    * Whether the list is rendered inline without using the popup.
    * @default false
    */
-  inline?: boolean;
+  inline?: boolean | undefined;
   /**
    * Determines if the popup enters a modal state when open.
    * - `true`: user interaction is limited to the popup: document page scroll is locked and pointer interactions on outside elements are disabled.
    * - `false`: user interaction with the rest of the document is allowed.
    * @default false
    */
-  modal?: boolean;
+  modal?: boolean | undefined;
   /**
    * The maximum number of items to display in the list.
    * @default -1
    */
-  limit?: number;
+  limit?: number | undefined;
   /**
    * Controls how the component behaves with respect to list filtering and inline autocompletion.
    * - `list` (default): items are dynamically filtered based on the input value. The input value does not change based on the active item.
@@ -188,23 +188,28 @@ 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';
+  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
+   */
+  formAutoComplete?: string | undefined;
   /**
    * The locale to use for string comparison.
    * Defaults to the user's runtime locale.
    */
-  locale?: Intl.LocalesArgument;
+  locale?: Intl.LocalesArgument | undefined;
   /**
    * Whether clicking an item should submit the owning form.
    * @default false
    */
-  submitOnItemClick?: boolean;
+  submitOnItemClick?: boolean | undefined;
   /**
    * INTERNAL: When `selectionMode` is `none`, controls whether selecting an item fills the input.
    */
-  fillInputOnItemPress?: boolean;
+  fillInputOnItemPress?: boolean | undefined;
 }
-export type ComboboxRootConditionalProps<Value, Mode extends SelectionMode = 'none'> = Omit<ComboboxRootProps<Value>, 'selectionMode' | 'selectedValue' | 'defaultSelectedValue' | 'onSelectedValueChange'> & {
+export type AriaComboboxProps<Value, Mode extends SelectionMode = 'none'> = ComboboxRootProps<Value> & {
   /**
    * How the combobox should remember the selected value.
    * - `single`: Remembers the last selected value.
@@ -212,24 +217,24 @@ export type ComboboxRootConditionalProps<Value, Mode extends SelectionMode = 'no
    * - `none`: Do not remember the selected value.
    * @default 'none'
    */
-  selectionMode?: Mode;
+  selectionMode?: Mode | undefined;
   /**
    * The selected value of the combobox. Use when controlled.
    */
-  selectedValue?: ComboboxItemValueType<Value, Mode>;
+  selectedValue?: ComboboxItemValueType<Value, Mode> | undefined;
   /**
    * The uncontrolled selected value of the combobox when it's initially rendered.
    *
    * To render a controlled combobox, use the `selectedValue` prop instead.
    */
-  defaultSelectedValue?: ComboboxItemValueType<Value, Mode> | null;
+  defaultSelectedValue?: (ComboboxItemValueType<Value, Mode> | null) | undefined;
   /**
    * Callback fired when the selected value of the combobox changes.
    */
-  onSelectedValueChange?: (value: ComboboxItemValueType<Value, Mode>, eventDetails: AriaCombobox.ChangeEventDetails) => void;
+  onSelectedValueChange?: ((value: ComboboxItemValueType<Value, Mode>, eventDetails: AriaCombobox.ChangeEventDetails) => void) | undefined;
 };
 export declare namespace AriaCombobox {
-  type Props<Value, Mode extends SelectionMode = 'none'> = ComboboxRootConditionalProps<Value, Mode>;
+  type Props<Value, Mode extends SelectionMode = 'none'> = AriaComboboxProps<Value, Mode>;
   interface State {}
   interface Actions {
     unmount: () => void;

package/esm/combobox/root/AriaCombobox.js

@@ -29,7 +29,7 @@ import { useOpenInteractionType } from "../../utils/useOpenInteractionType.js";
 import { useValueChanged } from "../../utils/useValueChanged.js";
 import { NOOP } from "../../utils/noop.js";
 import { stringifyAsLabel, stringifyAsValue, isGroupedItems } from "../../utils/resolveValueLabel.js";
-import { defaultItemEquality, findItemIndex, itemIncludes, removeItem } from "../../utils/itemEquality.js";
+import { compareItemEquality, defaultItemEquality, findItemIndex, removeItem, selectedValueIncludes } from "../../utils/itemEquality.js";
 import { INITIAL_LAST_HIGHLIGHT, NO_ACTIVE_VALUE } from "./utils/constants.js";
 
 /**
@@ -70,6 +70,7 @@ export function AriaCombobox(props) {
     modal = false,
     limit = -1,
     autoComplete = 'list',
+    formAutoComplete,
     locale,
     submitOnItemClick = false
   } = props;
@@ -399,17 +400,24 @@ export function AriaCombobox(props) {
     // If user is typing, ensure we don't auto-highlight on open due to a race
     // with the post-open effect that sets this flag.
     if (eventDetails.reason === REASONS.inputChange) {
-      const hasQuery = next.trim() !== '';
-      if (hasQuery) {
-        setQueryChangedAfterOpen(true);
-      }
-      // Defer index updates until after the filtered items have been derived to ensure
-      // `onItemHighlighted` receives the latest item.
-      pendingQueryHighlightRef.current = {
-        hasQuery
-      };
-      if (hasQuery && autoHighlightMode && store.state.activeIndex == null) {
-        store.set('activeIndex', 0);
+      const event = eventDetails.event;
+      const inputType = event.inputType;
+      // Treat composition commits as typed input; autofill may omit `inputType` or
+      // report `insertReplacementText`.
+      const isTypedInput = event.type === 'compositionend' || inputType != null && inputType !== '' && inputType !== 'insertReplacementText';
+      if (isTypedInput) {
+        const hasQuery = next.trim() !== '';
+        if (hasQuery) {
+          setQueryChangedAfterOpen(true);
+        }
+        // Defer index updates until after the filtered items have been derived to ensure
+        // `onItemHighlighted` receives the latest item.
+        pendingQueryHighlightRef.current = {
+          hasQuery
+        };
+        if (hasQuery && autoHighlightMode && store.state.activeIndex == null) {
+          store.set('activeIndex', 0);
+        }
       }
     }
     setInputValueUnwrapped(next);
@@ -431,7 +439,9 @@ export function AriaCombobox(props) {
     }
     if (!nextOpen && queryChangedAfterOpen) {
       if (single) {
-        setCloseQuery(query);
+        if (!inline) {
+          setCloseQuery(query);
+        }
         // Avoid a flicker when closing the popup with an empty query.
         if (query === '') {
           setQueryChangedAfterOpen(false);
@@ -472,17 +482,17 @@ export function AriaCombobox(props) {
     if (shouldFillInput) {
       setInputValue(stringifyAsLabel(nextValue, itemToStringLabel), createChangeEventDetails(eventDetails.reason, eventDetails.event));
     }
-    if (single && nextValue != null && eventDetails.reason !== REASONS.inputChange && queryChangedAfterOpen) {
+    if (single && nextValue != null && eventDetails.reason !== REASONS.inputChange && queryChangedAfterOpen && !inline) {
       setCloseQuery(query);
     }
   });
   const handleSelection = useStableCallback((event, passedValue) => {
-    let value = passedValue;
-    if (value === undefined) {
+    let itemValue = passedValue;
+    if (itemValue === undefined) {
       if (activeIndex === null) {
         return;
       }
-      value = valuesRef.current[activeIndex];
+      itemValue = valuesRef.current[activeIndex];
     }
     const targetEl = getTarget(event);
     const overrideEvent = selectionEventRef.current ?? event;
@@ -499,8 +509,8 @@ export function AriaCombobox(props) {
     }
     if (multiple) {
       const currentSelectedValue = Array.isArray(selectedValue) ? selectedValue : [];
-      const isCurrentlySelected = itemIncludes(currentSelectedValue, value, store.state.isItemEqualToValue);
-      const nextValue = isCurrentlySelected ? removeItem(currentSelectedValue, value, store.state.isItemEqualToValue) : [...currentSelectedValue, value];
+      const isCurrentlySelected = selectedValueIncludes(currentSelectedValue, itemValue, store.state.isItemEqualToValue);
+      const nextValue = isCurrentlySelected ? removeItem(currentSelectedValue, itemValue, store.state.isItemEqualToValue) : [...currentSelectedValue, itemValue];
       setSelectedValue(nextValue, eventDetails);
       const wasFiltering = inputRef.current ? inputRef.current.value.trim() !== '' : false;
       if (!wasFiltering) {
@@ -512,7 +522,7 @@ export function AriaCombobox(props) {
         setOpen(false, eventDetails);
       }
     } else {
-      setSelectedValue(value, eventDetails);
+      setSelectedValue(itemValue, eventDetails);
       setOpen(false, eventDetails);
     }
   });
@@ -659,46 +669,19 @@ export function AriaCombobox(props) {
       store.set('activeIndex', null);
       return;
     }
-    const nextActiveValue = candidateItems[storeActiveIndex];
-    const lastHighlightedValue = lastHighlightRef.current.value;
-    const isSameItem = lastHighlightedValue !== NO_ACTIVE_VALUE && store.state.isItemEqualToValue(nextActiveValue, lastHighlightedValue);
+    const itemValue = candidateItems[storeActiveIndex];
+    const previouslyHighlightedItemValue = lastHighlightRef.current.value;
+    const isSameItem = previouslyHighlightedItemValue !== NO_ACTIVE_VALUE && compareItemEquality(itemValue, previouslyHighlightedItemValue, store.state.isItemEqualToValue);
     if (lastHighlightRef.current.index !== storeActiveIndex || !isSameItem) {
       lastHighlightRef.current = {
-        value: nextActiveValue,
+        value: itemValue,
         index: storeActiveIndex
       };
-      store.state.onItemHighlighted(nextActiveValue, createGenericEventDetails(REASONS.none, undefined, {
+      store.state.onItemHighlighted(itemValue, createGenericEventDetails(REASONS.none, undefined, {
         index: storeActiveIndex
       }));
     }
   }, [activeIndex, autoHighlightMode, hasFilteredItemsProp, hasItems, flatFilteredItems, inline, open, store]);
-
-  // When the available items change, ensure the selected value(s) remain valid.
-  // - Single: if current selection is removed, fall back to defaultSelectedValue if it exists in the list; else null.
-  // - Multiple: drop any removed selections.
-  useIsoLayoutEffect(() => {
-    if (!items || selectionMode === 'none') {
-      return;
-    }
-    const registry = flatItems;
-    if (multiple) {
-      const current = Array.isArray(selectedValue) ? selectedValue : EMPTY_ARRAY;
-      const next = current.filter(v => itemIncludes(registry, v, store.state.isItemEqualToValue));
-      if (next.length !== current.length) {
-        setSelectedValue(next, createChangeEventDetails(REASONS.none));
-      }
-      return;
-    }
-    const isStillPresent = selectedValue == null || itemIncludes(registry, selectedValue, store.state.isItemEqualToValue);
-    if (isStillPresent) {
-      return;
-    }
-    let fallback = null;
-    if (defaultSelectedValue != null && itemIncludes(registry, defaultSelectedValue, store.state.isItemEqualToValue)) {
-      fallback = defaultSelectedValue;
-    }
-    setSelectedValue(fallback, createChangeEventDetails(REASONS.none));
-  }, [items, flatItems, multiple, selectionMode, selectedValue, defaultSelectedValue, store, setSelectedValue]);
   useIsoLayoutEffect(() => {
     if (selectionMode === 'none') {
       setFilled(String(inputValue) !== '');
@@ -733,12 +716,6 @@ export function AriaCombobox(props) {
     } else {
       validation.commit(selectedValue, true);
     }
-    if (multiple && store.state.selectedIndex !== null && (!Array.isArray(selectedValue) || selectedValue.length === 0)) {
-      setIndices({
-        activeIndex: null,
-        selectedIndex: null
-      });
-    }
     if (single && !hasInputValue && !inputInsidePopup) {
       const nextInputValue = stringifyAsLabel(selectedValue, itemToStringLabel);
       if (inputValue !== nextInputValue) {
@@ -810,7 +787,8 @@ export function AriaCombobox(props) {
     toggle: false,
     // Apply a small delay for touch to let iOS viewport centering settle.
     // This avoids top-bottom flip flickers if the preferred position is "top" when first tapping.
-    touchOpenDelay: inputInsidePopup ? 0 : 50
+    touchOpenDelay: inputInsidePopup ? 0 : 50,
+    reason: REASONS.inputPress
   });
   const dismiss = useDismiss(floatingRootContext, {
     enabled: !readOnly && !disabled && !inline,
@@ -922,9 +900,10 @@ export function AriaCombobox(props) {
   const hiddenInputRef = useMergedRefs(inputRefProp, validation.inputRef);
   const itemsContextValue = React.useMemo(() => ({
     query,
+    hasItems,
     filteredItems,
     flatFilteredItems
-  }), [query, filteredItems, flatFilteredItems]);
+  }), [query, hasItems, filteredItems, flatFilteredItems]);
   const serializedValue = React.useMemo(() => {
     if (Array.isArray(fieldRawValue)) {
       return '';
@@ -932,6 +911,7 @@ export function AriaCombobox(props) {
     return stringifyAsValue(fieldRawValue, itemToStringValue);
   }, [fieldRawValue, itemToStringValue]);
   const hasMultipleSelection = multiple && Array.isArray(selectedValue) && selectedValue.length > 0;
+  const hiddenInputName = multiple || selectionMode === 'none' ? undefined : name;
   const hiddenInputs = React.useMemo(() => {
     if (!multiple || !Array.isArray(selectedValue) || !name) {
       return null;
@@ -963,7 +943,7 @@ export function AriaCombobox(props) {
             return;
           }
           const nextValue = event.target.value;
-          const details = createChangeEventDetails(REASONS.inputChange, event.nativeEvent);
+          const details = createChangeEventDetails(REASONS.none, event.nativeEvent);
           function handleChange() {
             // Browser autofill only writes a single scalar value.
             if (multiple) {
@@ -1000,13 +980,15 @@ export function AriaCombobox(props) {
           }
         }
       }),
-      name: multiple || selectionMode === 'none' ? undefined : name,
+      id: id && hiddenInputName == null ? `${id}-hidden-input` : undefined,
+      name: hiddenInputName,
+      autoComplete: formAutoComplete,
       disabled: disabled,
       required: required && !hasMultipleSelection,
       readOnly: readOnly,
       value: serializedValue,
       ref: hiddenInputRef,
-      style: name ? visuallyHiddenInput : visuallyHidden,
+      style: hiddenInputName ? visuallyHiddenInput : visuallyHidden,
       tabIndex: -1,
       "aria-hidden": true
     }), hiddenInputs]

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

@@ -9,59 +9,64 @@ import { AriaCombobox } from "./AriaCombobox.js";
 export declare function ComboboxRoot<Value, Multiple extends boolean | undefined = false>(props: ComboboxRoot.Props<Value, Multiple>): React.JSX.Element;
 type ModeFromMultiple<Multiple extends boolean | undefined> = Multiple extends true ? 'multiple' : 'single';
 type ComboboxValueType<Value, Multiple extends boolean | undefined> = Multiple extends true ? Value[] : Value;
-export type ComboboxRootProps<Value, Multiple extends boolean | undefined = false> = Omit<AriaCombobox.Props<Value, ModeFromMultiple<Multiple>>, 'fillInputOnItemPress' | 'autoComplete' | 'submitOnItemClick' | 'autoHighlight' | 'keepHighlight' | 'highlightItemOnHover' | 'itemToStringLabel' | 'itemToStringValue' | 'isItemEqualToValue' | 'selectionMode' | 'defaultSelectedValue' | 'selectedValue' | 'onSelectedValueChange' | 'actionsRef' | 'onOpenChange' | 'onInputValueChange' | 'onItemHighlighted'> & {
+export type ComboboxRootProps<Value, Multiple extends boolean | undefined = false> = Omit<AriaCombobox.Props<Value, ModeFromMultiple<Multiple>>, 'fillInputOnItemPress' | 'autoComplete' | 'formAutoComplete' | 'submitOnItemClick' | 'autoHighlight' | 'keepHighlight' | 'highlightItemOnHover' | 'itemToStringLabel' | 'itemToStringValue' | 'isItemEqualToValue' | 'selectionMode' | 'defaultSelectedValue' | 'selectedValue' | 'onSelectedValueChange' | 'actionsRef' | 'onOpenChange' | 'onInputValueChange' | 'onItemHighlighted'> & {
   /**
    * Whether multiple items can be selected.
    * @default false
    */
-  multiple?: Multiple;
+  multiple?: Multiple | undefined;
+  /**
+   * Provides a hint to the browser for autofill.
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete
+   */
+  autoComplete?: string | undefined;
   /**
    * Whether the first matching item is highlighted automatically while filtering.
    * @default false
    */
-  autoHighlight?: boolean;
+  autoHighlight?: boolean | undefined;
   /**
    * Whether moving the pointer over items should highlight them.
    * Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.
    * @default true
    */
-  highlightItemOnHover?: boolean;
+  highlightItemOnHover?: 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.
    */
-  itemToStringLabel?: (itemValue: Value) => string;
+  itemToStringLabel?: ((itemValue: Value) => string) | undefined;
   /**
    * When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for form submission.
    * If the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop.
    */
-  itemToStringValue?: (itemValue: Value) => string;
+  itemToStringValue?: ((itemValue: Value) => string) | undefined;
   /**
    * Custom comparison logic used to determine if a combobox item value matches the current selected value. Useful when item values are objects without matching referentially.
    * Defaults to `Object.is` comparison.
    */
-  isItemEqualToValue?: (itemValue: Value, selectedValue: Value) => boolean;
+  isItemEqualToValue?: ((itemValue: Value, value: Value) => boolean) | undefined;
   /**
    * The uncontrolled selected value of the combobox when it's initially rendered.
    *
    * To render a controlled combobox, use the `value` prop instead.
    */
-  defaultValue?: ComboboxValueType<Value, Multiple> | null;
+  defaultValue?: (ComboboxValueType<Value, Multiple> | null) | undefined;
   /**
    * A ref to imperative actions.
    * - `unmount`: When specified, the combobox will not be unmounted when closed.
    * Instead, the `unmount` function must be called to unmount the combobox manually.
    * Useful when the combobox's animation is controlled by an external library.
    */
-  actionsRef?: React.RefObject<ComboboxRoot.Actions | null>;
+  actionsRef?: React.RefObject<ComboboxRoot.Actions | null> | undefined;
   /**
    * Event handler called when the popup is opened or closed.
    */
-  onOpenChange?: (open: boolean, eventDetails: ComboboxRoot.ChangeEventDetails) => void;
+  onOpenChange?: ((open: boolean, eventDetails: ComboboxRoot.ChangeEventDetails) => void) | undefined;
   /**
    * Event handler called when the input value changes.
    */
-  onInputValueChange?: (inputValue: string, eventDetails: ComboboxRoot.ChangeEventDetails) => void;
+  onInputValueChange?: ((inputValue: string, eventDetails: ComboboxRoot.ChangeEventDetails) => void) | undefined;
   /**
    * Callback fired when an item is highlighted or unhighlighted.
    * Receives the highlighted item value (or `undefined` if no item is highlighted) and event details with a `reason` property describing why the highlight changed.
@@ -70,15 +75,15 @@ export type ComboboxRootProps<Value, Multiple extends boolean | undefined = fals
    * - `'pointer'`: the highlight changed due to pointer hovering.
    * - `'none'`: the highlight changed programmatically.
    */
-  onItemHighlighted?: (highlightedValue: Value | undefined, eventDetails: ComboboxRoot.HighlightEventDetails) => void;
+  onItemHighlighted?: ((highlightedValue: Value | undefined, eventDetails: ComboboxRoot.HighlightEventDetails) => void) | undefined;
   /**
    * The selected value of the combobox. Use when controlled.
    */
-  value?: ComboboxValueType<Value, Multiple> | null;
+  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;
+  onValueChange?: ((value: ComboboxValueType<Value, Multiple> | (Multiple extends true ? never : null), eventDetails: ComboboxRoot.ChangeEventDetails) => void) | undefined;
 };
 export type ComboboxRootState = AriaCombobox.State;
 export type ComboboxRootActions = AriaCombobox.Actions;

package/esm/combobox/root/ComboboxRoot.js

@@ -16,6 +16,7 @@ export function ComboboxRoot(props) {
     defaultValue,
     value,
     onValueChange,
+    autoComplete,
     ...other
   } = props;
   return /*#__PURE__*/_jsx(AriaCombobox, {
@@ -23,6 +24,7 @@ export function ComboboxRoot(props) {
     selectionMode: multiple ? 'multiple' : 'single',
     selectedValue: value,
     defaultSelectedValue: defaultValue,
-    onSelectedValueChange: onValueChange
+    onSelectedValueChange: onValueChange,
+    formAutoComplete: autoComplete
   });
 }

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

@@ -2,6 +2,7 @@ import * as React from 'react';
 import { ComboboxStore } from "../store.js";
 export interface ComboboxDerivedItemsContext {
   query: string;
+  hasItems: boolean;
   filteredItems: any[];
   flatFilteredItems: any[];
 }

package/esm/combobox/root/ComboboxRootContext.js

@@ -1,3 +1,5 @@
+'use client';
+
 import _formatErrorMessage from "@base-ui/utils/formatErrorMessage";
 import * as React from 'react';
 export const ComboboxRootContext = /*#__PURE__*/React.createContext(undefined);

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

@@ -3,7 +3,7 @@ export interface UseFilterOptions extends Intl.CollatorOptions {
    * The locale to use for string comparison.
    * Defaults to the user's runtime locale.
    */
-  locale?: Intl.LocalesArgument;
+  locale?: Intl.LocalesArgument | undefined;
 }
 export interface Filter {
   contains: <Item>(item: Item, query: string, itemToString?: (item: Item) => string) => boolean;
@@ -20,7 +20,7 @@ export interface UseComboboxFilterOptions extends UseFilterOptions {
    * Whether the combobox is in multiple selection mode.
    * @default false
    */
-  multiple?: boolean;
+  multiple?: boolean | undefined;
   /**
    * The current value of the combobox.
    */

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

@@ -0,0 +1,4 @@
+/**
+ * Returns the internally filtered items.
+ */
+export declare function useFilteredItems<T>(): T[];