[combobox] Support primitive item values

Lets Combobox infer primitive values from supported `{ value, label }` item
shapes, e.g. `items={[{ value: "banana", label: "Banana" }]}` with
`defaultValue="banana"` or `<Combobox.Item value="banana" />`, while preserving
the exact rendered value shape for `<Combobox.Item value={item}>`. Inferred
values drive selection, highlight, scroll-into-view, typeahead, autofill, and
labels. The public API is unchanged. Select is unchanged.

Author: atomiks

docs/src/app/(docs)/react/components/combobox/page.mdx

@@ -74,7 +74,10 @@ import { Combobox } from '@base-ui/react/combobox';
 ## TypeScript
 
 Combobox infers the item type from the `defaultValue` or `value` props passed to `<Combobox.Root>`.
-The type of items held in the `items` array must also match the `value` prop type passed to `<Combobox.Item>`.
+
+When a non-virtualized `items` array uses the full `{ value, label }` shape, `<Combobox.Item>` can use either the whole item or its `value` field.
+Virtualized comboboxes do not support this primitive value inference.
+For other item shapes, the `items` array type should match the `value` prop type passed to `<Combobox.Item>`.
 
 ## Examples
 

docs/src/app/(docs)/react/components/combobox/types.md

@@ -95,24 +95,28 @@ function ComboboxItemInner(props: ComboboxItemInnerProps) {
   }, [hasRegistered, virtualized, index, indexProp, store]);
 
   useIsoLayoutEffect(() => {
-    if (!hasRegistered || hasItems) {
+    if (!hasRegistered || (hasItems && virtualized)) {
       return undefined;
     }
 
+    // Register the rendered item value so the visible registry preserves its exact
+    // shape (a primitive `value`, or the whole item for `value={item}`) for selection,
+    // highlight callbacks, autofill, and typeahead. Virtualized `items` lists are
+    // owned by the root registry because it may directly reference the `items` array.
     const visibleMap = store.state.valuesRef.current;
     visibleMap[index] = itemValue;
 
     // Stable registry that doesn't depend on filtering. Assume that no
     // filtering had occurred at this point; otherwise, an `items` prop is
     // required.
-    if (selectionMode !== 'none') {
+    if (!hasItems && selectionMode !== 'none') {
       store.state.allValuesRef.current.push(itemValue);
     }
 
     return () => {
       delete visibleMap[index];
     };
-  }, [hasRegistered, hasItems, index, itemValue, store, selectionMode]);
+  }, [hasRegistered, hasItems, virtualized, index, itemValue, store, selectionMode]);
 
   useIsoLayoutEffect(() => {
     if (!open) {

packages/react/src/combobox/item/ComboboxItem.tsx

@@ -49,6 +49,10 @@ import { NOOP } from '../../internals/noop';
 import { FOCUSABLE_POPUP_PROPS } from '../../utils/popups';
 import { mergeProps } from '../../merge-props';
 import {
+  findItemIndexByValue,
+  inferItemValue,
+  resolveLabelString,
+  resolveRenderedValue,
   stringifyAsLabel,
   stringifyAsValue,
   Group,
@@ -175,6 +179,12 @@ export function AriaCombobox<Value = any, Mode extends SelectionMode = 'none'>(
   const single = selectionMode === 'single';
   const hasInputValue = inputValueProp !== undefined || defaultInputValueProp !== undefined;
   const hasItems = items !== undefined;
+
+  // Resolving a primitive selected value to its `{ value, label }` item's label is only
+  // supported for non-virtualized lists (virtualized selection sync matches whole items),
+  // so virtualized lists resolve labels from the value's own shape to keep the displayed
+  // label consistent with what can actually be highlighted.
+  const labelItems = virtualized ? undefined : items;
   const hasFilteredItemsProp = filteredItemsProp !== undefined;
 
   let autoHighlightMode: false | 'input-change' | 'always';
@@ -212,7 +222,7 @@ export function AriaCombobox<Value = any, Mode extends SelectionMode = 'none'>(
         return defaultInputValueProp ?? '';
       }
       if (single) {
-        return stringifyAsLabel(selectedValue, itemToStringLabel);
+        return resolveLabelString(selectedValue, labelItems, itemToStringLabel, isItemEqualToValue);
       }
       return '';
     },
@@ -235,7 +245,15 @@ export function AriaCombobox<Value = any, Mode extends SelectionMode = 'none'>(
   const isGrouped = isGroupedItems(items);
   const query = closeQuery ?? (inputValue === '' ? '' : String(inputValue).trim());
 
-  const selectedLabelString = single ? stringifyAsLabel(selectedValue, itemToStringLabel) : '';
+  // Resolving the label can scan `items`, so memoize to avoid repeating it on every
+  // render (e.g. each keystroke) when the selection and items are unchanged.
+  const selectedLabelString = React.useMemo(
+    () =>
+      single
+        ? resolveLabelString(selectedValue, labelItems, itemToStringLabel, isItemEqualToValue)
+        : '',
+    [single, selectedValue, labelItems, itemToStringLabel, isItemEqualToValue],
+  );
 
   const shouldBypassFiltering =
     single &&
@@ -306,12 +324,11 @@ export function AriaCombobox<Value = any, Mode extends SelectionMode = 'none'>(
     if (filterQuery === '') {
       return limit > -1
         ? flatItems.slice(0, limit)
-        : // The cast here is done as `flatItems` is readonly.
-          // valuesRef.current, a mutable ref, can be set to `flatFilteredItems`, which may
-          // reference this exact readonly value, creating a mutation risk.
-          // However, <Combobox.Item> can never mutate this value as the mutating effect
-          // bails early when `items` is provided, and this is only ever returned
-          // when `items` is provided due to the early return at the top of this hook.
+        : // The cast here is done as `flatItems` is readonly. Reusing the prop's array is
+          // safe: in the non-virtualized path `valuesRef` is a distinct array (mounted
+          // items write their own slots and the root effect fills the rest), and in the
+          // virtualized path `valuesRef` aliases this array but is only ever read by index,
+          // never mutated.
           (flatItems as Value[]);
     }
 
@@ -461,12 +478,15 @@ export function AriaCombobox<Value = any, Mode extends SelectionMode = 'none'>(
     nameProp,
   );
 
-  const forceMount = useStableCallback(() => {
+  const forceMount = useStableCallback((renderItems = false) => {
     if (items) {
       // Ensure typeahead works on a closed list.
       labelsRef.current = flatFilteredItems.map((item) =>
         stringifyAsLabel(item, itemToStringLabel),
       );
+      if (renderItems && !virtualized) {
+        store.set('forceMounted', true);
+      }
     } else {
       store.set('forceMounted', true);
     }
@@ -647,7 +667,7 @@ export function AriaCombobox<Value = any, Mode extends SelectionMode = 'none'>(
 
       if (shouldFillInput) {
         setInputValue(
-          stringifyAsLabel(nextValue, itemToStringLabel),
+          resolveLabelString(nextValue, labelItems, itemToStringLabel, isItemEqualToValue),
           createChangeEventDetails(eventDetails.reason, eventDetails.event),
         );
       }
@@ -771,7 +791,7 @@ export function AriaCombobox<Value = any, Mode extends SelectionMode = 'none'>(
           setInputValue('', createChangeEventDetails(REASONS.inputClear));
         }
       } else {
-        const stringVal = stringifyAsLabel(selectedValue, itemToStringLabel);
+        const stringVal = selectedLabelString;
         if (inputRef.current && inputRef.current.value !== stringVal) {
           // If no selection was made, treat this as clearing the typed filter.
           const reason = stringVal === '' ? REASONS.inputClear : REASONS.none;
@@ -805,42 +825,74 @@ export function AriaCombobox<Value = any, Mode extends SelectionMode = 'none'>(
 
   React.useImperativeHandle(props.actionsRef, () => ({ unmount: handleUnmount }), [handleUnmount]);
 
+  const navigationValue =
+    multiple && Array.isArray(selectedValue)
+      ? selectedValue[selectedValue.length - 1]
+      : selectedValue;
+
+  // Derive the selected value's index in the (unfiltered) `items`. Non-virtualized
+  // lists can match the full item (object `value={item}`) or its inferred value
+  // (primitive `value` against a `{ value, label }` entry). Only the closed state is
+  // consumed (the syncing effect bails while open), so skip the scan while open to
+  // avoid rescanning large lists on every selection change during open interactions.
+  const itemsSelectedIndex = React.useMemo(() => {
+    if (open || selectionMode === 'none' || !items) {
+      return -1;
+    }
+    if (virtualized) {
+      return findItemIndex(flatItems, navigationValue, isItemEqualToValue);
+    }
+    return findItemIndexByValue(flatItems, navigationValue, isItemEqualToValue);
+  }, [open, selectionMode, items, virtualized, flatItems, navigationValue, isItemEqualToValue]);
+
   useIsoLayoutEffect(
     function syncSelectedIndex() {
+      // Snapshot the selected index only while the popup is closed, so selecting,
+      // deselecting, clearing, or filtering while open doesn't move the highlight off
+      // the active item. Drives initial highlight and scroll-into-view on open.
       if (open || selectionMode === 'none') {
         return;
       }
 
-      const registry = items ? flatItems : allValuesRef.current;
-
-      if (multiple) {
-        const currentValue = Array.isArray(selectedValue) ? selectedValue : [];
-        const lastValue = currentValue[currentValue.length - 1];
-        const lastIndex = findItemIndex(registry, lastValue, isItemEqualToValue);
-        setIndices({ selectedIndex: lastIndex === -1 ? null : lastIndex });
-      } else {
-        const index = findItemIndex(registry, selectedValue, isItemEqualToValue);
-        setIndices({ selectedIndex: index === -1 ? null : index });
-      }
+      // With `items` the index is the derived value above; without `items`, match
+      // against the values registered by mounted items.
+      const index = items
+        ? itemsSelectedIndex
+        : findItemIndex(allValuesRef.current, navigationValue, isItemEqualToValue);
+      setIndices({ selectedIndex: index === -1 ? null : index });
     },
     [
       open,
-      selectedValue,
-      items,
       selectionMode,
-      flatItems,
-      multiple,
+      items,
+      itemsSelectedIndex,
+      navigationValue,
       isItemEqualToValue,
       setIndices,
     ],
   );
 
   useIsoLayoutEffect(() => {
     if (items) {
-      valuesRef.current = flatFilteredItems;
+      if (virtualized) {
+        valuesRef.current = flatFilteredItems;
+        listRef.current.length = flatFilteredItems.length;
+        return;
+      }
+
+      // Mounted items register their own rendered value (preserving its exact shape).
+      // Fill any remaining slots in place with an inferred value so the registry stays
+      // complete without clobbering those writes.
+      const visibleMap = valuesRef.current;
+      visibleMap.length = flatFilteredItems.length;
+      for (let index = 0; index < flatFilteredItems.length; index += 1) {
+        if (visibleMap[index] === undefined) {
+          visibleMap[index] = inferItemValue(flatFilteredItems[index]);
+        }
+      }
       listRef.current.length = flatFilteredItems.length;
     }
-  }, [items, flatFilteredItems]);
+  }, [items, virtualized, flatFilteredItems]);
 
   useIsoLayoutEffect(() => {
     const pendingHighlight = pendingQueryHighlightRef.current;
@@ -890,7 +942,13 @@ export function AriaCombobox<Value = any, Mode extends SelectionMode = 'none'>(
       return;
     }
 
-    const itemValue = candidateItems[storeActiveIndex];
+    const candidateItem = candidateItems[storeActiveIndex];
+    // Surface the rendered item value so highlight callbacks report the same shape used
+    // for selection. Non-virtualized lists can fall back to the inferred value for any
+    // slot not registered by a mounted item; virtualized lists keep the item shape.
+    const itemValue = hasItems
+      ? resolveRenderedValue(valuesRef.current[storeActiveIndex], candidateItem, virtualized)
+      : candidateItem;
     const previouslyHighlightedItemValue = lastHighlightRef.current.value;
     const isSameItem =
       previouslyHighlightedItemValue !== NO_ACTIVE_VALUE &&
@@ -916,6 +974,7 @@ export function AriaCombobox<Value = any, Mode extends SelectionMode = 'none'>(
     inline,
     open,
     store,
+    virtualized,
   ]);
 
   useIsoLayoutEffect(() => {
@@ -966,7 +1025,7 @@ export function AriaCombobox<Value = any, Mode extends SelectionMode = 'none'>(
     validation.change(selectedValue);
 
     if (single && !hasInputValue && !inputInsidePopup) {
-      const nextInputValue = stringifyAsLabel(selectedValue, itemToStringLabel);
+      const nextInputValue = selectedLabelString;
 
       if (inputValue !== nextInputValue) {
         setInputValue(nextInputValue, createChangeEventDetails(REASONS.none));
@@ -990,7 +1049,7 @@ export function AriaCombobox<Value = any, Mode extends SelectionMode = 'none'>(
       return;
     }
 
-    const nextInputValue = stringifyAsLabel(selectedValue, itemToStringLabel);
+    const nextInputValue = selectedLabelString;
 
     if (inputValue !== nextInputValue) {
       setInputValue(nextInputValue, createChangeEventDetails(REASONS.none));
@@ -1529,6 +1588,12 @@ 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.
+   * In non-virtualized lists, when items use the `{ value, label }` shape, a primitive
+   * `<Combobox.Item value>` resolves its text label from the matching item. In single
+   * selection mode `<Combobox.Value>` and the input render that label instead of the raw
+   * value; in multiple selection mode the input stays the query field, so only
+   * `<Combobox.Value>` renders the selected labels.
+   * Virtualized lists do not support this primitive value inference.
    */
   items?: readonly any[] | readonly Group<any>[] | undefined;
   /**