[combobox] Support primitive item values

Author: atomiks

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

@@ -73,8 +73,27 @@ 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>`.
+Combobox infers the selected value type from `defaultValue`, `value`, or the return value of `itemToValue`.
+Source items and explicitly specified `<Combobox.Item value>` props can have different types. Use `itemToValue` to derive selection values automatically when rendering a collection: filtering and collection children receive source items, while change callbacks and equality checks receive mapped values.
+Mapped values must be defined and unique. An explicit item `value` takes precedence over `itemToValue`.
+
+For example, the source items can be user objects while selection uses only their IDs. Their `label` fields are used automatically for display and filtering:
+
+```tsx title="Mapping source items to selection values"
+type User = { id: string; label: string; email: string };
+
+const users: User[] = [
+  { id: 'u1', label: 'Alice Johnson', email: 'alice@example.com' },
+  { id: 'u2', label: 'Bob Smith', email: 'bob@example.com' },
+];
+
+<Combobox.Root items={users} itemToValue={(user) => user.id}>
+  <Combobox.Input />
+  <Combobox.List>
+    {(user) => <Combobox.Item key={user.id}>{user.label}</Combobox.Item>}
+  </Combobox.List>
+</Combobox.Root>;
+```
 
 ## Examples
 

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

@@ -461,7 +461,7 @@ An input combined with a list of predefined items to select.
   - useFilteredItems
 - Exports:
   - Combobox - Root
-    - Props: actionsRef, autoComplete, autoHighlight, children, defaultInputValue, defaultOpen, defaultValue, disabled, filter, filteredItems, form, grid, highlightItemOnHover, id, inline, inputRef, inputValue, isItemEqualToValue, itemToStringLabel, itemToStringValue, items, limit, locale, loopFocus, modal, multiple, name, onInputValueChange, onItemHighlighted, onOpenChange, onOpenChangeComplete, onValueChange, open, openOnInputClick, readOnly, required, value, virtualized
+    - Props: actionsRef, autoComplete, autoHighlight, children, defaultInputValue, defaultOpen, defaultValue, disabled, filter, filteredItems, form, grid, highlightItemOnHover, id, inline, inputRef, inputValue, isItemEqualToValue, itemToStringLabel, itemToStringValue, itemToValue, items, limit, locale, loopFocus, modal, multiple, name, onInputValueChange, onItemHighlighted, onOpenChange, onOpenChangeComplete, onValueChange, open, openOnInputClick, readOnly, required, value, virtualized
   - Combobox - Trigger
     - Props: className, disabled, nativeButton, render, style
     - Data Attributes: data-dirty, data-disabled, data-filled, data-focused, data-invalid, data-list-empty, data-placeholder, data-popup-open, data-popup-side, data-pressed, data-readonly, data-required, data-touched, data-valid
@@ -527,7 +527,7 @@ An input combined with a list of predefined items to select.
   - Combobox - useFilter
     - Parameters: options
   - Combobox - useFilteredItems
-- Types: Combobox.Arrow.Props, Combobox.Arrow.State, Combobox.Backdrop.Props, Combobox.Backdrop.State, Combobox.Chip.Props, Combobox.Chip.State, Combobox.ChipRemove.Props, Combobox.ChipRemove.State, Combobox.Chips.Props, Combobox.Chips.State, Combobox.Clear.Props, Combobox.Clear.State, Combobox.Collection.Props, Combobox.Collection.State, Combobox.Empty.Props, Combobox.Empty.State, Combobox.Group.Props, Combobox.Group.State, Combobox.GroupLabel.Props, Combobox.GroupLabel.State, Combobox.Icon.Props, Combobox.Icon.State, Combobox.Input.Props, Combobox.Input.State, Combobox.InputGroup.Props, Combobox.InputGroup.State, Combobox.Item.Props, Combobox.Item.State, Combobox.ItemIndicator.Props, Combobox.ItemIndicator.State, Combobox.Label.Props, Combobox.Label.State, Combobox.List.Props, Combobox.List.State, Combobox.Popup.Props, Combobox.Popup.State, Combobox.Portal.Props, Combobox.Portal.State, Combobox.Positioner.Props, Combobox.Positioner.State, Combobox.Root.Actions, Combobox.Root.ChangeEventDetails, Combobox.Root.ChangeEventReason, Combobox.Root.HighlightEventDetails, Combobox.Root.HighlightEventReason, Combobox.Root.Props, Combobox.Root.State, Combobox.Row.Props, Combobox.Row.State, Combobox.Separator.Props, Combobox.Separator.State, Combobox.Status.Props, Combobox.Status.State, Combobox.Trigger.Props, Combobox.Trigger.State, Combobox.Value.Props, Combobox.Value.State
+- Types: Combobox.Arrow.Props, Combobox.Arrow.State, Combobox.Backdrop.Props, Combobox.Backdrop.State, Combobox.Chip.Props, Combobox.Chip.State, Combobox.ChipRemove.Props, Combobox.ChipRemove.State, Combobox.Chips.Props, Combobox.Chips.State, Combobox.Clear.Props, Combobox.Clear.State, Combobox.Collection.Props, Combobox.Collection.State, Combobox.Empty.Props, Combobox.Empty.State, Combobox.Group.Props, Combobox.Group.State, Combobox.GroupLabel.Props, Combobox.GroupLabel.State, Combobox.Icon.Props, Combobox.Icon.State, Combobox.Input.Props, Combobox.Input.State, Combobox.InputGroup.Props, Combobox.InputGroup.State, Combobox.Item.Props, Combobox.Item.State, Combobox.ItemIndicator.Props, Combobox.ItemIndicator.State, Combobox.Label.Props, Combobox.Label.State, Combobox.List.Props, Combobox.List.State, Combobox.Popup.Props, Combobox.Popup.State, Combobox.Portal.Props, Combobox.Portal.State, Combobox.Positioner.Props, Combobox.Positioner.State, Combobox.Root.Actions, Combobox.Root.ChangeEventDetails, Combobox.Root.ChangeEventReason, Combobox.Root.HighlightEventDetails, Combobox.Root.HighlightEventReason, Combobox.Root.MappedProps, Combobox.Root.Props, Combobox.Root.State, Combobox.Row.Props, Combobox.Row.State, Combobox.Separator.Props, Combobox.Separator.State, Combobox.Status.Props, Combobox.Status.State, Combobox.Trigger.Props, Combobox.Trigger.State, Combobox.Value.Props, Combobox.Value.State
 
 </details>
 

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

@@ -39,6 +39,9 @@ const groupItemsReadonly = [
   }}
 />;
 
+// @ts-expect-error - itemToValue is a Combobox-only prop
+<Autocomplete.Root items={objectItems} itemToValue={(item) => item.value} />;
+
 <Autocomplete.Root
   items={groupItemsReadonly}
   itemToStringValue={(item) => {

packages/react/src/autocomplete/root/AutocompleteRoot.spec.tsx

@@ -14,6 +14,22 @@ describe('<Autocomplete.Root />', () => {
 
   const { render, renderToString } = createRenderer();
 
+  it('does not forward itemToValue supplied through an untyped spread', async () => {
+    const itemToValue = vi.fn(() => 'mapped');
+    const rootProps: any = { items: ['alpha'], itemToValue };
+
+    await render(
+      <Autocomplete.Root {...rootProps}>
+        <Autocomplete.Input />
+        <Autocomplete.List>
+          <Autocomplete.Item value="alpha">alpha</Autocomplete.Item>
+        </Autocomplete.List>
+      </Autocomplete.Root>,
+    );
+
+    expect(itemToValue).not.toHaveBeenCalled();
+  });
+
   describe('keyboard interactions', () => {
     it('closes popup on Tab after selecting with Enter and typing again', async () => {
       const { user } = await render(

packages/react/src/autocomplete/root/AutocompleteRoot.test.tsx

@@ -39,8 +39,9 @@ export function AutocompleteRoot<ItemValue>(
     onValueChange,
     mode = 'list',
     itemToStringValue,
+    itemToValue: ignoredItemToValue,
     ...other
-  } = props;
+  } = props as AutocompleteRoot.Props<ItemValue> & { itemToValue?: unknown };
 
   const enableInline = mode === 'inline' || mode === 'both';
   const staticItems = mode === 'inline' || mode === 'none';
@@ -155,6 +156,7 @@ export interface AutocompleteRootProps<ItemValue> extends Omit<
   | 'onSelectedValueChange'
   | 'fillInputOnItemPress'
   | 'itemToStringValue'
+  | 'itemToValue'
   | 'isItemEqualToValue'
   // Different names
   | 'inputValue' // value

packages/react/src/autocomplete/root/AutocompleteRoot.tsx

@@ -1,6 +1,9 @@
 'use client';
 import * as React from 'react';
-import { useComboboxDerivedItemsContext } from '../root/ComboboxRootContext';
+import {
+  ComboboxHasItemsContext,
+  useComboboxDerivedItemsContext,
+} from '../root/ComboboxRootContext';
 import { useGroupCollectionContext } from './GroupCollectionContext';
 
 /**
@@ -14,7 +17,7 @@ import { useGroupCollectionContext } from './GroupCollectionContext';
 export function ComboboxCollection(props: ComboboxCollection.Props): React.JSX.Element | null {
   const { children } = props;
 
-  const { filteredItems } = useComboboxDerivedItemsContext();
+  const { filteredItems, itemToValue } = useComboboxDerivedItemsContext();
   const groupContext = useGroupCollectionContext();
 
   const itemsToRender = groupContext ? groupContext.items : filteredItems;
@@ -23,7 +26,28 @@ export function ComboboxCollection(props: ComboboxCollection.Props): React.JSX.E
     return null;
   }
 
-  return <React.Fragment>{itemsToRender.map(children)}</React.Fragment>;
+  if (!itemToValue) {
+    return <React.Fragment>{itemsToRender.map(children)}</React.Fragment>;
+  }
+
+  return (
+    <React.Fragment>
+      {itemsToRender.map((item, index) => {
+        const child = children(item, index);
+        // A distinct context value intentionally associates each rendered child with its item.
+        // eslint-disable-next-line react/jsx-no-constructed-context-values
+        const contextValue = [itemToValue(item)] as const;
+        return (
+          <ComboboxHasItemsContext.Provider
+            key={(child as React.ReactElement | null)?.key ?? index}
+            value={contextValue}
+          >
+            {child}
+          </ComboboxHasItemsContext.Provider>
+        );
+      })}
+    </React.Fragment>
+  );
 }
 
 export interface ComboboxCollectionState {}

packages/react/src/combobox/collection/ComboboxCollection.tsx

@@ -31,15 +31,16 @@ interface ComboboxItemInnerProps {
    * composite list registration order.
    */
   indexFromFilter: number | undefined;
+  mappedValue?: any;
 }
 
 function ComboboxItemInner(props: ComboboxItemInnerProps) {
-  const { componentProps, forwardedRef, virtualized, indexFromFilter } = props;
+  const { componentProps, forwardedRef, virtualized, indexFromFilter, mappedValue } = props;
   const {
     render,
     className,
     style,
-    value: itemValue = null,
+    value: itemValueProp = null,
     index: indexProp,
     disabled = false,
     nativeButton = false,
@@ -55,7 +56,8 @@ function ComboboxItemInner(props: ComboboxItemInnerProps) {
 
   const store = useComboboxRootContext();
   const isRow = useComboboxRowContext();
-  const hasItems = useComboboxHasItemsContext();
+  const hasItemsContext = useComboboxHasItemsContext();
+  const hasItems = hasItemsContext !== false;
 
   const selectionMode = useStore(store, selectors.selectionMode);
   const readOnly = useStore(store, selectors.readOnly);
@@ -64,6 +66,16 @@ function ComboboxItemInner(props: ComboboxItemInnerProps) {
   const selectable = selectionMode !== 'none';
   const index = indexProp ?? (virtualized ? (indexFromFilter ?? -1) : listItem.index);
   const hasRegistered = listItem.index !== -1;
+  const hasExplicitValue = componentProps.value !== undefined;
+
+  let itemValue = itemValueProp;
+  if (!hasExplicitValue) {
+    if (typeof hasItemsContext !== 'boolean') {
+      [itemValue] = hasItemsContext;
+    } else if (mappedValue !== undefined) {
+      itemValue = mappedValue;
+    }
+  }
 
   const rootId = useStore(store, selectors.id);
   const highlighted = useStore(store, selectors.isActive, index);
@@ -221,13 +233,26 @@ function ComboboxItemVirtualizedIndex(props: {
 
   const store = useComboboxRootContext();
   const isItemEqualToValue = useStore(store, selectors.isItemEqualToValue);
-  const { flatFilteredItems } = useComboboxDerivedItemsContext();
+  const { flatFilteredItems, flatFilteredValues } = useComboboxDerivedItemsContext();
+
+  let indexFromFilter = componentProps.index;
+  if (indexFromFilter == null) {
+    indexFromFilter = findItemIndex(
+      flatFilteredValues,
+      componentProps.value ?? null,
+      isItemEqualToValue,
+    );
+    if (indexFromFilter === -1) {
+      indexFromFilter = findItemIndex(
+        flatFilteredItems,
+        componentProps.value ?? null,
+        isItemEqualToValue,
+      );
+    }
+  }
 
-  const indexFromFilter = findItemIndex(
-    flatFilteredItems,
-    componentProps.value ?? null,
-    isItemEqualToValue,
-  );
+  const mappedValue =
+    componentProps.value === undefined ? flatFilteredValues[indexFromFilter] : undefined;
 
   // Only reached when `virtualized` is true (see the wrapper below).
   return (
@@ -236,6 +261,7 @@ function ComboboxItemVirtualizedIndex(props: {
       forwardedRef={forwardedRef}
       virtualized
       indexFromFilter={indexFromFilter}
+      mappedValue={mappedValue}
     />
   );
 }
@@ -257,7 +283,7 @@ export const ComboboxItem = React.memo(
     // `virtualized` (and whether an item provides an explicit `index`) must be stable for an
     // item's lifetime: the two branches return different component types, so flipping it at
     // runtime remounts the item and resets its refs and effects.
-    if (virtualized && componentProps.index == null) {
+    if (virtualized) {
       return (
         <ComboboxItemVirtualizedIndex componentProps={componentProps} forwardedRef={forwardedRef} />
       );