feat: [combobox] add createItems for id-based values

apps/www/src/content/docs/components/combobox/demo.ts

@@ -149,3 +149,40 @@ export const controlledDemo = {
     );
   }`
 };
+
+export const createItemsDemo = {
+  type: 'code',
+  code: `
+  function CreateItemsDemo() {
+    const users = [
+      { id: "u1", name: "Jane Doe" },
+      { id: "u2", name: "John Smith" },
+      { id: "u3", name: "Ada Lovelace" }
+    ];
+    const items = React.useMemo(
+      () =>
+        Combobox.createItems(users, {
+          getValue: user => user.id,
+          getLabel: user => user.name
+        }),
+      []
+    );
+    const [value, setValue] = React.useState(null);
+
+    return (
+      <Flex direction="column" gap={5}>
+        <Text>Selected ID: {value || "None"}</Text>
+        <Combobox items={items} value={value} onValueChange={setValue}>
+          <Combobox.Input placeholder="Pick a user" />
+          <Combobox.Content>
+            {user => (
+              <Combobox.Item key={user.id} value={user.id}>
+                {user.name}
+              </Combobox.Item>
+            )}
+          </Combobox.Content>
+        </Combobox>
+      </Flex>
+    );
+  }`
+};

apps/www/src/content/docs/components/combobox/index.mdx

@@ -12,6 +12,7 @@ import {
   iconDemo,
   withFieldDemo,
   controlledDemo,
+  createItemsDemo,
 } from "./demo.ts";
 
 <Demo data={playground} />
@@ -69,6 +70,14 @@ Use `value` and `onValueChange` for controlled behavior.
 
 <Demo data={controlledDemo} />
 
+### Using IDs as values
+
+When your app stores IDs instead of item objects, wrap the data with `Combobox.createItems`. `getValue` returns the value that `value` and `onValueChange` use. `getLabel` returns the text shown in the input and used for filtering. Pass a function as the child of `Combobox.Content` to render each item that matches the input.
+
+Create the collection at module scope for static data. For data that changes, wrap it in `React.useMemo` keyed by the data.
+
+<Demo data={createItemsDemo} />
+
 ## API Reference
 
 Root and input first, then the parts that make up the popup list.

apps/www/src/content/docs/components/combobox/props.ts

@@ -49,6 +49,14 @@ export interface ComboboxRootProps {
    * @default false
    */
   modal?: boolean;
+
+  /**
+   * The items to filter. Accepts an array of items or a collection from `Combobox.createItems`.
+   * When set, the root filters the items and `Combobox.Content` can render them with a function child.
+   *
+   * @remarks `unknown[] | ReturnType<typeof Combobox.createItems>`
+   */
+  items?: unknown[];
 }
 
 export interface ComboboxInputProps {
@@ -96,6 +104,13 @@ export interface ComboboxContentProps {
    * @defaultValue The theme's `radius`
    */
   radius?: 'none' | 'small' | 'medium' | 'large' | 'full';
+
+  /**
+   * The list content. Pass a function to render each item that matches the input when `items` is set on the root.
+   */
+  children?:
+    | React.ReactNode
+    | ((item: unknown, index: number) => React.ReactNode);
 }
 
 export interface ComboboxItemProps {

packages/react/components/combobox/__tests__/combobox.test.tsx

@@ -484,3 +484,88 @@ describe('Combobox', () => {
     });
   });
 });
+
+describe('Combobox.createItems', () => {
+  const USERS = [
+    { id: 'u1', name: 'Jane Doe' },
+    { id: 'u2', name: 'John Smith' },
+    { id: 'u3', name: 'Ada Lovelace' }
+  ];
+  const USER_ITEMS = Combobox.createItems(USERS, {
+    getValue: user => user.id,
+    getLabel: user => user.name
+  });
+
+  const UserCombobox = (props: {
+    defaultValue?: string | null;
+    onValueChange?: (value: string | null) => void;
+  }) => (
+    <Combobox items={USER_ITEMS} {...props}>
+      <Combobox.Input placeholder='Pick a user' />
+      <Combobox.Content>
+        {(user: (typeof USERS)[number]) => (
+          <Combobox.Item key={user.id} value={user.id}>
+            {user.name}
+          </Combobox.Item>
+        )}
+      </Combobox.Content>
+    </Combobox>
+  );
+
+  it('calls onValueChange with the derived value', async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(<UserCombobox onValueChange={onValueChange} />);
+
+    await user.click(screen.getByRole('combobox'));
+    await clickOption(await screen.findByText('John Smith'));
+
+    expect(onValueChange).toHaveBeenCalledWith('u2');
+  });
+
+  it('shows the derived label for the selected value', () => {
+    render(<UserCombobox defaultValue='u3' />);
+    expect(screen.getByRole('combobox')).toHaveValue('Ada Lovelace');
+  });
+
+  it('filters by the derived label', async () => {
+    const user = userEvent.setup();
+    render(<UserCombobox />);
+
+    await user.type(screen.getByRole('combobox'), 'jo');
+
+    await waitFor(() => {
+      expect(screen.getByText('John Smith')).toBeInTheDocument();
+      expect(screen.queryByText('Jane Doe')).not.toBeInTheDocument();
+      expect(screen.queryByText('Ada Lovelace')).not.toBeInTheDocument();
+    });
+  });
+});
+
+describe('Combobox.createItems chips', () => {
+  const USERS = [
+    { id: 'u1', name: 'Jane Doe' },
+    { id: 'u2', name: 'John Smith' }
+  ];
+  const USER_ITEMS = Combobox.createItems(USERS, {
+    getValue: user => user.id,
+    getLabel: user => user.name
+  });
+
+  it('labels chips with the derived label', () => {
+    render(
+      <Combobox items={USER_ITEMS} multiple defaultValue={['u2']}>
+        <Combobox.Input placeholder='Pick users' />
+        <Combobox.Content>
+          {(user: (typeof USERS)[number]) => (
+            <Combobox.Item key={user.id} value={user.id}>
+              {user.name}
+            </Combobox.Item>
+          )}
+        </Combobox.Content>
+      </Combobox>
+    );
+    expect(screen.getByText('John Smith')).toBeInTheDocument();
+    expect(screen.queryByText('u2')).not.toBeInTheDocument();
+  });
+});

packages/react/components/combobox/combobox-content.tsx

@@ -2,22 +2,27 @@
 
 import { Combobox as ComboboxPrimitive } from '@base-ui/react';
 import { cx } from 'class-variance-authority';
+import type { ReactNode } from 'react';
 import { type Radius, radiusStyle } from '../../shared/radius';
 import { useThemeInjection } from '../theme/portal';
 import styles from './combobox.module.css';
 import { useComboboxContext } from './combobox-root';
 
-export interface ComboboxContentProps
+export interface ComboboxContentProps<Item = unknown>
   extends Omit<
       ComboboxPrimitive.Positioner.Props,
-      'render' | 'className' | 'style'
+      'render' | 'className' | 'style' | 'children'
     >,
-    ComboboxPrimitive.Popup.Props {
+    Omit<ComboboxPrimitive.Popup.Props, 'children'> {
   /** Corner radius for this popup only. Overrides the theme's `radius`. */
   radius?: Radius;
+  /**
+   * The list content. Pass a function to render each item that matches the input when `items` is set on the root.
+   */
+  children?: ReactNode | ((item: Item, index: number) => ReactNode);
 }
 
-export const ComboboxContent = ({
+export const ComboboxContent = <Item,>({
   ref,
   className,
   children,
@@ -28,7 +33,7 @@ export const ComboboxContent = ({
   sideOffset = 4,
   radius,
   ...positionerProps
-}: ComboboxContentProps) => {
+}: ComboboxContentProps<Item>) => {
   const { inputContainerRef } = useComboboxContext();
   const theme = useThemeInjection();
   return (

packages/react/components/combobox/combobox-input.tsx

@@ -13,7 +13,7 @@ export interface ComboboxInputProps
   > {}
 
 export const ComboboxInput = ({ ref, ...props }: ComboboxInputProps) => {
-  const { multiple, inputContainerRef, value, onValueChange } =
+  const { multiple, inputContainerRef, value, onValueChange, getLabel } =
     useComboboxContext();
   return (
     <ComboboxPrimitive.Input
@@ -24,7 +24,7 @@ export const ComboboxInput = ({ ref, ...props }: ComboboxInputProps) => {
           chips={
             multiple && Array.isArray(value)
               ? value.map(val => ({
-                  label: val,
+                  label: getLabel(val),
                   onRemove: () =>
                     onValueChange?.((value as string[])?.filter(v => v !== val))
                 }))

packages/react/components/combobox/combobox-items.ts

@@ -0,0 +1,35 @@
+import { Combobox as ComboboxPrimitive } from '@base-ui/react';
+
+type LabelLookup = (value: unknown) => string | undefined;
+
+const labelLookups = new WeakMap<object, LabelLookup>();
+
+/**
+ * Wraps Base UI's `createItems` and records how to label each value, so chips
+ * can show labels instead of raw values.
+ */
+export const createItems: typeof ComboboxPrimitive.createItems = (
+  data,
+  options
+) => {
+  const collection = ComboboxPrimitive.createItems(data, options);
+  labelLookups.set(collection, value => {
+    for (const entry of data ?? []) {
+      const items =
+        typeof entry === 'object' && entry !== null && 'items' in entry
+          ? entry.items
+          : [entry];
+      for (const item of items) {
+        if (options.getValue(item) === value) return options.getLabel(item);
+      }
+    }
+    return undefined;
+  });
+  return collection;
+};
+
+/** Returns the label for `value` when `items` came from `createItems`. */
+export function getItemLabel(items: unknown, value: unknown) {
+  if (typeof items !== 'object' || items === null) return undefined;
+  return labelLookups.get(items)?.(value);
+}

packages/react/components/combobox/combobox-root.tsx

@@ -11,6 +11,7 @@ import {
   useState
 } from 'react';
 import { useFieldContext } from '../field';
+import { getItemLabel } from './combobox-items';
 
 interface ComboboxContextValue<Value = string> {
   multiple: boolean;
@@ -19,6 +20,7 @@ interface ComboboxContextValue<Value = string> {
   inputContainerRef: RefObject<HTMLDivElement | null>;
   value: Value | Value[] | null | undefined;
   onValueChange?: (value: Value | Value[] | null) => void;
+  getLabel: (value: Value) => string;
 }
 
 const ComboboxContext = createContext<
@@ -37,35 +39,35 @@ export const useComboboxContext = <
   return context as ComboboxContextValue<Value>;
 };
 
-export interface BaseComboboxRootProps<Value>
+export interface BaseComboboxRootProps<Value, Item = Value>
   extends Omit<
-    ComboboxPrimitive.Root.Props<Value, boolean>,
+    ComboboxPrimitive.Root.Props<Value, boolean, Item>,
     'onValueChange' | 'onInputValueChange' | 'multiple'
   > {
   onInputValueChange?: (inputValue: string) => void;
 }
 
-export interface SingleComboboxProps<Value = string>
-  extends BaseComboboxRootProps<Value> {
+export interface SingleComboboxProps<Value = string, Item = Value>
+  extends BaseComboboxRootProps<Value, Item> {
   multiple?: false;
   value?: Value | null;
   defaultValue?: Value | null;
   onValueChange?: (value: Value | null) => void;
 }
 
-export interface MultipleComboboxProps<Value = string>
-  extends BaseComboboxRootProps<Value> {
+export interface MultipleComboboxProps<Value = string, Item = Value>
+  extends BaseComboboxRootProps<Value, Item> {
   multiple: true;
   value?: Value[];
   defaultValue?: Value[];
   onValueChange?: (value: Value[]) => void;
 }
 
-export type ComboboxRootProps<Value = string> =
-  | SingleComboboxProps<Value>
-  | MultipleComboboxProps<Value>;
+export type ComboboxRootProps<Value = string, Item = Value> =
+  | SingleComboboxProps<Value, Item>
+  | MultipleComboboxProps<Value, Item>;
 
-export const ComboboxRoot = <Value extends unknown | unknown[]>({
+export const ComboboxRoot = <Value extends unknown | unknown[], Item = Value>({
   multiple = false,
   children,
   onValueChange,
@@ -75,7 +77,7 @@ export const ComboboxRoot = <Value extends unknown | unknown[]>({
   items,
   required,
   ...props
-}: ComboboxRootProps<Value>) => {
+}: ComboboxRootProps<Value, Item>) => {
   const fieldContext = useFieldContext();
   const resolvedRequired = required ?? fieldContext?.required;
 
@@ -105,11 +107,11 @@ export const ComboboxRoot = <Value extends unknown | unknown[]>({
     ) => {
       setInternalValue(value);
       if (multiple) {
-        (onValueChange as MultipleComboboxProps<Value>['onValueChange'])?.(
-          value as Value[]
-        );
+        (
+          onValueChange as MultipleComboboxProps<Value, Item>['onValueChange']
+        )?.(value as Value[]);
       } else {
-        (onValueChange as SingleComboboxProps<Value>['onValueChange'])?.(
+        (onValueChange as SingleComboboxProps<Value, Item>['onValueChange'])?.(
           value as Value | null
         );
       }
@@ -124,7 +126,8 @@ export const ComboboxRoot = <Value extends unknown | unknown[]>({
       hasItems: !!items,
       inputContainerRef,
       value: computedValue,
-      onValueChange: handleValueChange
+      onValueChange: handleValueChange,
+      getLabel: (value: Value) => getItemLabel(items, value) ?? String(value)
     }),
     [multiple, inputValue, items, computedValue, handleValueChange]
   );

packages/react/components/combobox/combobox.tsx

@@ -2,6 +2,7 @@ import { Combobox as ComboboxPrimitive } from '@base-ui/react';
 import { ComboboxContent } from './combobox-content';
 import { ComboboxInput } from './combobox-input';
 import { ComboboxItem } from './combobox-item';
+import { createItems } from './combobox-items';
 import {
   ComboboxGroup,
   ComboboxLabel,
@@ -17,5 +18,6 @@ export const Combobox = Object.assign(ComboboxRoot, {
   Label: ComboboxLabel,
   Separator: ComboboxSeparator,
   useFilter: ComboboxPrimitive.useFilter,
-  useFilteredItems: ComboboxPrimitive.useFilteredItems
+  useFilteredItems: ComboboxPrimitive.useFilteredItems,
+  createItems
 });