From 488ab857be29394b825f2c3020fd27a697b6814c Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Mon, 26 Jan 2026 11:28:06 -0800
Subject: [PATCH 01/11] feat: Add support for multi-select ComboBox

---
 .../@react-aria/combobox/src/useComboBox.ts   |   6 +-
 .../combobox/src/useComboBoxState.ts          | 177 +++++++++++++-----
 .../@react-types/autocomplete/src/index.d.ts  |   4 +-
 packages/@react-types/combobox/src/index.d.ts |  40 +++-
 .../react-aria-components/src/ComboBox.tsx    |  12 +-
 .../stories/ComboBox.stories.tsx              | 101 +++++++++-
 6 files changed, 277 insertions(+), 63 deletions(-)

diff --git a/packages/@react-aria/combobox/src/useComboBox.ts b/packages/@react-aria/combobox/src/useComboBox.ts
index c8db04c19cc..946cef824db 100644
--- a/packages/@react-aria/combobox/src/useComboBox.ts
+++ b/packages/@react-aria/combobox/src/useComboBox.ts
@@ -12,7 +12,7 @@
 
 import {announce} from '@react-aria/live-announcer';
 import {AriaButtonProps} from '@react-types/button';
-import {AriaComboBoxProps} from '@react-types/combobox';
+import {AriaComboBoxProps, SelectionMode} from '@react-types/combobox';
 import {ariaHideOutside} from '@react-aria/overlays';
 import {AriaListBoxOptions, getItemId, listData} from '@react-aria/listbox';
 import {BaseEvent, DOMAttributes, KeyboardDelegate, LayoutDelegate, PressEvent, RefObject, RouterOptions, ValidationResult} from '@react-types/shared';
@@ -29,7 +29,7 @@ import {useLocalizedStringFormatter} from '@react-aria/i18n';
 import {useMenuTrigger} from '@react-aria/menu';
 import {useTextField} from '@react-aria/textfield';
 
-export interface AriaComboBoxOptions<T> extends Omit<AriaComboBoxProps<T>, 'children'> {
+export interface AriaComboBoxOptions<T, M extends SelectionMode = 'single'> extends Omit<AriaComboBoxProps<T, M>, 'children'> {
   /** The ref for the input element. */
   inputRef: RefObject<HTMLInputElement | null>,
   /** The ref for the list box popover. */
@@ -69,7 +69,7 @@ export interface ComboBoxAria<T> extends ValidationResult {
  * @param props - Props for the combo box.
  * @param state - State for the select, as returned by `useComboBoxState`.
  */
-export function useComboBox<T>(props: AriaComboBoxOptions<T>, state: ComboBoxState<T>): ComboBoxAria<T> {
+export function useComboBox<T, M extends SelectionMode = 'single'>(props: AriaComboBoxOptions<T, M>, state: ComboBoxState<T, M>): ComboBoxAria<T> {
   let {
     buttonRef,
     popoverRef,
diff --git a/packages/@react-stately/combobox/src/useComboBoxState.ts b/packages/@react-stately/combobox/src/useComboBoxState.ts
index e2cce7de048..6e8a5b08016 100644
--- a/packages/@react-stately/combobox/src/useComboBoxState.ts
+++ b/packages/@react-stately/combobox/src/useComboBoxState.ts
@@ -10,18 +10,45 @@
  * governing permissions and limitations under the License.
  */
 
-import {Collection, CollectionStateBase, FocusStrategy, Key, Node} from '@react-types/shared';
-import {ComboBoxProps, MenuTriggerAction} from '@react-types/combobox';
+import {Collection, CollectionStateBase, FocusStrategy, Key, Node, Selection} from '@react-types/shared';
+import {ComboBoxProps, MenuTriggerAction, SelectionMode, ValueType} from '@react-types/combobox';
 import {FormValidationState, useFormValidationState} from '@react-stately/form';
 import {getChildNodes} from '@react-stately/collections';
-import {ListCollection, SingleSelectListState, useSingleSelectListState} from '@react-stately/list';
+import {ListCollection, ListState, useListState} from '@react-stately/list';
 import {OverlayTriggerState, useOverlayTriggerState} from '@react-stately/overlays';
 import {useCallback, useEffect, useMemo, useRef, useState} from 'react';
 import {useControlledState} from '@react-stately/utils';
 
-export interface ComboBoxState<T> extends SingleSelectListState<T>, OverlayTriggerState, FormValidationState {
-  /** The default selected key. */
+export interface ComboBoxState<T, M extends SelectionMode = 'single'> extends ListState<T>, OverlayTriggerState, FormValidationState {
+  /**
+   * The key for the first selected item.
+   * @deprecated
+   */
+  readonly selectedKey: Key | null,
+
+  /**
+   * The default selected key.
+   * @deprecated
+   */
   readonly defaultSelectedKey: Key | null,
+  /**
+   * Sets the selected key.
+   * @deprecated
+   */
+  setSelectedKey(key: Key | null): void,
+  /** The current combobox value. */
+  readonly value: ValueType<M>,
+  /** The default combobox value. */
+  readonly defaultValue: ValueType<M>,
+  /** Sets the combobox value. */
+  setValue(value: Key | readonly Key[] | null): void,
+  /**
+   * The value of the first selected item.
+   * @deprecated
+   */
+  readonly selectedItem: Node<T> | null,
+  /** The value of the selected items. */
+  readonly selectedItems: Node<T>[],
   /** The current value of the combo box input. */
   inputValue: string,
   /** The default value of the combo box input. */
@@ -46,7 +73,7 @@ export interface ComboBoxState<T> extends SingleSelectListState<T>, OverlayTrigg
 
 type FilterFn = (textValue: string, inputValue: string) => boolean;
 
-export interface ComboBoxStateOptions<T> extends Omit<ComboBoxProps<T>, 'children'>, CollectionStateBase<T> {
+export interface ComboBoxStateOptions<T, M extends SelectionMode = 'single'> extends Omit<ComboBoxProps<T, M>, 'children'>, CollectionStateBase<T> {
   /** The filter function used to determine if a option should be included in the combo box list. */
   defaultFilter?: FilterFn,
   /** Whether the combo box allows the menu to be open when the collection is empty. */
@@ -60,51 +87,95 @@ export interface ComboBoxStateOptions<T> extends Omit<ComboBoxProps<T>, 'childre
  * of items from props and manages the option selection state of the combo box. In addition, it tracks the input value,
  * focus state, and other properties of the combo box.
  */
-export function useComboBoxState<T extends object>(props: ComboBoxStateOptions<T>): ComboBoxState<T> {
+export function useComboBoxState<T extends object, M extends SelectionMode = 'single'>(props: ComboBoxStateOptions<T, M>): ComboBoxState<T> {
   let {
     defaultFilter,
     menuTrigger = 'input',
     allowsEmptyCollection = false,
     allowsCustomValue,
-    shouldCloseOnBlur = true
+    shouldCloseOnBlur = true,
+    selectionMode = 'single' as SelectionMode
   } = props;
 
   let [showAllItems, setShowAllItems] = useState(false);
   let [isFocused, setFocusedState] = useState(false);
   let [focusStrategy, setFocusStrategy] = useState<FocusStrategy | null>(null);
 
-  let onSelectionChange = (key) => {
-    if (props.onSelectionChange) {
-      props.onSelectionChange(key);
-    }
+  let defaultValue = useMemo(() => {
+    return props.defaultValue !== undefined ? props.defaultValue : (selectionMode === 'single' ? props.defaultSelectedKey ?? null : []) as ValueType<M>;
+  }, [props.defaultValue, props.defaultSelectedKey, selectionMode]);
+  let value = useMemo(() => {
+    return props.value !== undefined ? props.value : (selectionMode === 'single' ? props.selectedKey : undefined) as ValueType<M>;
+  }, [props.value, props.selectedKey, selectionMode]);
+  let [controlledValue, setControlledValue] = useControlledState<Key | readonly Key[] | null>(value, defaultValue, props.onChange as any);
+  // Only display the first selected item if in single selection mode but the value is an array.
+  let displayValue: ValueType<M> = selectionMode === 'single' && Array.isArray(controlledValue) ? controlledValue[0] : controlledValue;
+
+  let setValue = (value: Key | Key[] | null) => {
+    if (selectionMode === 'single') {
+      let key = Array.isArray(value) ? value[0] ?? null : value;
+      setControlledValue(key);
+      if (key !== displayValue) {
+        props.onSelectionChange?.(key);
+      }
+    } else {
+      let keys: Key[] = [];
+      if (Array.isArray(value)) {
+        keys = value;
+      } else if (value != null) {
+        keys = [value];
+      }
 
-    // If key is the same, reset the inputValue and close the menu
-    // (scenario: user clicks on already selected option)
-    if (key === selectedKey) {
-      resetInputValue();
-      closeMenu();
+      setControlledValue(keys);
     }
   };
 
-  let {collection,
+  let {
+    collection,
     selectionManager,
-    selectedKey,
-    setSelectedKey,
-    selectedItem,
     disabledKeys
-  } = useSingleSelectListState({
+  } = useListState({
     ...props,
-    onSelectionChange,
-    items: props.items ?? props.defaultItems
+    items: props.items ?? props.defaultItems,
+    selectionMode,
+    disallowEmptySelection: selectionMode === 'single',
+    allowDuplicateSelectionEvents: true,
+    selectedKeys: useMemo(() => convertValue(displayValue), [displayValue]),
+    onSelectionChange: (keys: Selection) => {
+      // impossible, but TS doesn't know that
+      if (keys === 'all') {
+        return;
+      }
+
+      if (selectionMode === 'single') {
+        let key = keys.values().next().value ?? null;
+        if (key === displayValue) {
+          props.onSelectionChange?.(key);
+          // If key is the same, reset the inputValue and close the menu
+          // (scenario: user clicks on already selected option)
+          resetInputValue();
+          closeMenu();
+        } else {
+          setValue(key);
+        }
+      } else {
+        setValue([...keys]);
+      }
+    }
   });
 
+  let selectedKey = selectionMode === 'single' ? selectionManager.firstSelectedKey : null;
+  let selectedItems = useMemo(() => {
+    return [...selectionManager.selectedKeys].map(key => collection.getItem(key)).filter(item => item != null);
+  }, [selectionManager.selectedKeys, collection]);
+
   let [inputValue, setInputValue] = useControlledState(
     props.inputValue,
     getDefaultInputValue(props.defaultInputValue, selectedKey, collection) || '',
     props.onInputChange
   );
-  let [initialSelectedKey] = useState(selectedKey);
-  let [initialValue] = useState(inputValue);
+  let [initialValue] = useState(displayValue);
+  let [initialInputValue] = useState(inputValue);
 
   // Preserve original collection so we can show all items on demand
   let originalCollection = collection;
@@ -196,7 +267,7 @@ export function useComboBoxState<T extends object>(props: ComboBoxStateOptions<T
     setInputValue(itemText);
   };
 
-  let lastSelectedKey = useRef(props.selectedKey ?? props.defaultSelectedKey ?? null);
+  let lastValueRef = useRef(displayValue);
   let lastSelectedKeyText = useRef(
     selectedKey != null ? collection.getItem(selectedKey)?.textValue ?? '' : ''
   );
@@ -228,8 +299,9 @@ export function useComboBoxState<T extends object>(props: ComboBoxStateOptions<T
 
     // Close when an item is selected.
     if (
-      selectedKey != null &&
-      selectedKey !== lastSelectedKey.current
+      displayValue != null &&
+      displayValue !== lastValueRef.current &&
+      selectionMode === 'single'
     ) {
       closeMenu();
     }
@@ -239,10 +311,10 @@ export function useComboBoxState<T extends object>(props: ComboBoxStateOptions<T
       selectionManager.setFocusedKey(null);
       setShowAllItems(false);
 
-      // Set selectedKey to null when the user clears the input.
+      // Set value to null when the user clears the input.
       // If controlled, this is the application developer's responsibility.
-      if (inputValue === '' && (props.inputValue === undefined || props.selectedKey === undefined)) {
-        setSelectedKey(null);
+      if (inputValue === '' && (props.inputValue === undefined || value === undefined)) {
+        setValue(null);
       }
     }
 
@@ -250,8 +322,8 @@ export function useComboBoxState<T extends object>(props: ComboBoxStateOptions<T
     // Do nothing if both inputValue and selectedKey are controlled.
     // In this case, it's the user's responsibility to update inputValue in onSelectionChange.
     if (
-      selectedKey !== lastSelectedKey.current &&
-      (props.inputValue === undefined || props.selectedKey === undefined)
+      displayValue !== lastValueRef.current &&
+      (props.inputValue === undefined || value === undefined)
     ) {
       resetInputValue();
     } else if (lastValue !== inputValue) {
@@ -263,20 +335,20 @@ export function useComboBoxState<T extends object>(props: ComboBoxStateOptions<T
     // Only reset if the user isn't currently within the field so we don't erroneously modify user input.
     // If inputValue is controlled, it is the user's responsibility to update the inputValue when items change.
     let selectedItemText = selectedKey != null ? collection.getItem(selectedKey)?.textValue ?? '' : '';
-    if (!isFocused && selectedKey != null && props.inputValue === undefined && selectedKey === lastSelectedKey.current) {
+    if (!isFocused && selectedKey != null && props.inputValue === undefined && selectedKey === lastValueRef.current) {
       if (lastSelectedKeyText.current !== selectedItemText) {
         setLastValue(selectedItemText);
         setInputValue(selectedItemText);
       }
     }
 
-    lastSelectedKey.current = selectedKey;
+    lastValueRef.current = displayValue;
     lastSelectedKeyText.current = selectedItemText;
   });
 
   let validation = useFormValidationState({
     ...props,
-    value: useMemo(() => ({inputValue, selectedKey}), [inputValue, selectedKey])
+    value: useMemo(() => Array.isArray(displayValue) && displayValue.length === 0 ? null : ({inputValue, value: displayValue as any, selectedKey}), [inputValue, selectedKey, displayValue])
   });
 
   // Revert input value and close menu
@@ -289,14 +361,15 @@ export function useComboBoxState<T extends object>(props: ComboBoxStateOptions<T
   };
 
   let commitCustomValue = () => {
-    lastSelectedKey.current = null;
-    setSelectedKey(null);
+    let value = selectionMode === 'multiple' ? [] : null;
+    lastValueRef.current = value as any;
+    setValue(value);
     closeMenu();
   };
 
   let commitSelection = () => {
     // If multiple things are controlled, call onSelectionChange
-    if (props.selectedKey !== undefined && props.inputValue !== undefined) {
+    if (value !== undefined && props.inputValue !== undefined) {
       props.onSelectionChange?.(selectedKey);
 
       // Stop menu from reopening from useEffect
@@ -327,7 +400,7 @@ export function useComboBoxState<T extends object>(props: ComboBoxStateOptions<T
       if (selectedKey === selectionManager.focusedKey) {
         commitSelection();
       } else {
-        setSelectedKey(selectionManager.focusedKey);
+        selectionManager.select(selectionManager.focusedKey);
       }
     } else {
       commitValue();
@@ -366,7 +439,7 @@ export function useComboBoxState<T extends object>(props: ComboBoxStateOptions<T
     }
   }, [triggerState.isOpen, originalCollection, filteredCollection, showAllItems, lastCollection]);
 
-  let defaultSelectedKey = props.defaultSelectedKey ?? initialSelectedKey;
+  let defaultSelectedKey = props.defaultSelectedKey ?? (props.selectionMode === 'single' ? initialValue as Key : null);
 
   return {
     ...validation,
@@ -376,16 +449,20 @@ export function useComboBoxState<T extends object>(props: ComboBoxStateOptions<T
     open,
     close: commitValue,
     selectionManager,
+    value: displayValue as any,
+    defaultValue: defaultValue ?? initialValue as any,
+    setValue,
     selectedKey,
+    selectedItems,
     defaultSelectedKey,
-    setSelectedKey,
+    setSelectedKey: setValue,
     disabledKeys,
     isFocused,
     setFocused,
-    selectedItem,
+    selectedItem: selectedItems[0] ?? null,
     collection: displayedCollection,
     inputValue,
-    defaultInputValue: getDefaultInputValue(props.defaultInputValue, defaultSelectedKey, collection) ?? initialValue,
+    defaultInputValue: getDefaultInputValue(props.defaultInputValue, defaultSelectedKey, collection) ?? initialInputValue,
     setInputValue,
     commit,
     revert
@@ -423,3 +500,13 @@ function getDefaultInputValue(defaultInputValue: string | null | undefined, sele
 
   return defaultInputValue;
 }
+
+function convertValue(value: Key | Key[] | null | undefined) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (value === null) {
+    return [];
+  }
+  return Array.isArray(value) ? value : [value];
+}
diff --git a/packages/@react-types/autocomplete/src/index.d.ts b/packages/@react-types/autocomplete/src/index.d.ts
index 561dfdf53d4..ba87e43a0d2 100644
--- a/packages/@react-types/autocomplete/src/index.d.ts
+++ b/packages/@react-types/autocomplete/src/index.d.ts
@@ -15,7 +15,7 @@ import {AriaSearchFieldProps, SearchFieldProps} from '@react-types/searchfield';
 import {MenuTriggerAction} from '@react-types/combobox';
 import {ReactElement} from 'react';
 
-export interface SearchAutocompleteProps<T> extends CollectionBase<T>, Omit<SearchFieldProps, 'onSubmit' | 'defaultValue' | 'value'> {
+export interface SearchAutocompleteProps<T> extends CollectionBase<T>, Omit<SearchFieldProps, 'onChange' | 'onSubmit' | 'defaultValue' | 'value'> {
   /** The list of SearchAutocomplete items (uncontrolled). */
   defaultItems?: Iterable<T>,
   /** The list of SearchAutocomplete items (controlled). */
@@ -44,7 +44,7 @@ export interface SearchAutocompleteProps<T> extends CollectionBase<T>, Omit<Sear
   onSubmit?: (value: string | null, key: Key | null) => void
 }
 
-export interface AriaSearchAutocompleteProps<T> extends SearchAutocompleteProps<T>, Omit<AriaSearchFieldProps, 'onSubmit' | 'defaultValue' | 'value'>, DOMProps, AriaLabelingProps {}
+export interface AriaSearchAutocompleteProps<T> extends SearchAutocompleteProps<T>, Omit<AriaSearchFieldProps, 'onChange' | 'onSubmit' | 'defaultValue' | 'value'>, DOMProps, AriaLabelingProps {}
 
 export interface SpectrumSearchAutocompleteProps<T> extends SpectrumTextInputBase, Omit<AriaSearchAutocompleteProps<T>, 'menuTrigger' | 'isInvalid' | 'validationState' | 'validate'>, SpectrumFieldValidation<string>, SpectrumLabelableProps, StyleProps, Omit<AsyncLoadable, 'isLoading'> {
   /**
diff --git a/packages/@react-types/combobox/src/index.d.ts b/packages/@react-types/combobox/src/index.d.ts
index 3558c274dc8..295b010d260 100644
--- a/packages/@react-types/combobox/src/index.d.ts
+++ b/packages/@react-types/combobox/src/index.d.ts
@@ -23,32 +23,58 @@ import {
   Key,
   LabelableProps,
   LoadingState,
-  SingleSelection,
   SpectrumFieldValidation,
   SpectrumLabelableProps,
   SpectrumTextInputBase,
   StyleProps,
   TextInputBase,
-  Validation
+  Validation,
+  ValueBase
 } from '@react-types/shared';
 
 export type MenuTriggerAction = 'focus' | 'input' | 'manual';
+export type SelectionMode = 'single' | 'multiple';
+export type ValueType<M extends SelectionMode> = M extends 'single' ? Key | null : Key[];
+type ValidationType<M extends SelectionMode> = M extends 'single' ? Key : Key[];
 
-export interface ComboBoxValidationValue {
-  /** The selected key in the ComboBox. */
+export interface ComboBoxValidationValue<M extends SelectionMode = 'single'> {
+  /**
+   * The selected key in the ComboBox.
+   * @deprecated
+   */
   selectedKey: Key | null,
+  /** The keys of the currently selected items. */
+  value: ValidationType<M>,
   /** The value of the ComboBox input. */
   inputValue: string
 }
 
-export interface ComboBoxProps<T> extends CollectionBase<T>, Omit<SingleSelection, 'disallowEmptySelection' | 'onSelectionChange'>, InputBase, TextInputBase, Validation<ComboBoxValidationValue>, FocusableProps<HTMLInputElement>, LabelableProps, HelpTextProps {
+export interface ComboBoxProps<T, M extends SelectionMode = 'single'> extends CollectionBase<T>, InputBase, ValueBase<ValueType<M>>, TextInputBase, Validation<ComboBoxValidationValue>, FocusableProps<HTMLInputElement>, LabelableProps, HelpTextProps {
   /** The list of ComboBox items (uncontrolled). */
   defaultItems?: Iterable<T>,
   /** The list of ComboBox items (controlled). */
   items?: Iterable<T>,
   /** Method that is called when the open state of the menu changes. Returns the new open state and the action that caused the opening of the menu. */
   onOpenChange?: (isOpen: boolean, menuTrigger?: MenuTriggerAction) => void,
-  /** Handler that is called when the selection changes. */
+  /**
+   * Whether single or multiple selection is enabled.
+   * @default 'single'
+   */
+  selectionMode?: M,
+  /**
+   * The currently selected key in the collection (controlled).
+   * @deprecated
+   */
+  selectedKey?: Key | null,
+  /**
+   * The initial selected key in the collection (uncontrolled).
+   * @deprecated
+   */
+  defaultSelectedKey?: Key,
+  /**
+   * Handler that is called when the selection changes.
+   * @deprecated
+   */
   onSelectionChange?: (key: Key | null) => void,
   /** The value of the ComboBox input (controlled). */
   inputValue?: string,
@@ -70,7 +96,7 @@ export interface ComboBoxProps<T> extends CollectionBase<T>, Omit<SingleSelectio
   menuTrigger?: MenuTriggerAction
 }
 
-export interface AriaComboBoxProps<T> extends ComboBoxProps<T>, DOMProps, InputDOMProps, AriaLabelingProps {
+export interface AriaComboBoxProps<T, M extends SelectionMode = 'single'> extends ComboBoxProps<T, M>, DOMProps, InputDOMProps, AriaLabelingProps {
   /** Whether keyboard navigation is circular. */
   shouldFocusWrap?: boolean
 }
diff --git a/packages/react-aria-components/src/ComboBox.tsx b/packages/react-aria-components/src/ComboBox.tsx
index 5efbdd26945..53f3da93dca 100644
--- a/packages/react-aria-components/src/ComboBox.tsx
+++ b/packages/react-aria-components/src/ComboBox.tsx
@@ -39,6 +39,8 @@ import {PopoverContext} from './Popover';
 import React, {createContext, ForwardedRef, forwardRef, useCallback, useMemo, useRef, useState} from 'react';
 import {TextContext} from './Text';
 
+type SelectionMode = 'single' | 'multiple';
+
 export interface ComboBoxRenderProps {
   /**
    * Whether the combobox is currently open.
@@ -62,7 +64,7 @@ export interface ComboBoxRenderProps {
   isRequired: boolean
 }
 
-export interface ComboBoxProps<T extends object> extends Omit<AriaComboBoxProps<T>, 'children' | 'placeholder' | 'label' | 'description' | 'errorMessage' | 'validationState' | 'validationBehavior'>, RACValidation, RenderProps<ComboBoxRenderProps>, SlotProps, GlobalDOMAttributes<HTMLDivElement> {
+export interface ComboBoxProps<T extends object, M extends SelectionMode = 'single'> extends Omit<AriaComboBoxProps<T, M>, 'children' | 'placeholder' | 'label' | 'description' | 'errorMessage' | 'validationState' | 'validationBehavior'>, RACValidation, RenderProps<ComboBoxRenderProps>, SlotProps, GlobalDOMAttributes<HTMLDivElement> {
   /**
    * The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state.
    * @default 'react-aria-ComboBox'
@@ -82,13 +84,13 @@ export interface ComboBoxProps<T extends object> extends Omit<AriaComboBoxProps<
   isTriggerUpWhenOpen?: boolean
 }
 
-export const ComboBoxContext = createContext<ContextValue<ComboBoxProps<any>, HTMLDivElement>>(null);
-export const ComboBoxStateContext = createContext<ComboBoxState<any> | null>(null);
+export const ComboBoxContext = createContext<ContextValue<ComboBoxProps<any, SelectionMode>, HTMLDivElement>>(null);
+export const ComboBoxStateContext = createContext<ComboBoxState<any, SelectionMode> | null>(null);
 
 /**
  * A combo box combines a text input with a listbox, allowing users to filter a list of options to items matching a query.
  */
-export const ComboBox = /*#__PURE__*/ (forwardRef as forwardRefType)(function ComboBox<T extends object>(props: ComboBoxProps<T>, ref: ForwardedRef<HTMLDivElement>) {
+export const ComboBox = /*#__PURE__*/ (forwardRef as forwardRefType)(function ComboBox<T extends object, M extends SelectionMode = 'single'>(props: ComboBoxProps<T, M>, ref: ForwardedRef<HTMLDivElement>) {
   [props, ref] = useContextProps(props, ref, ComboBoxContext);
   let {children, isDisabled = false, isInvalid = false, isRequired = false} = props;
   let content = useMemo(() => (
@@ -116,7 +118,7 @@ export const ComboBox = /*#__PURE__*/ (forwardRef as forwardRefType)(function Co
 const CLEAR_CONTEXTS = [LabelContext, ButtonContext, InputContext, GroupContext, TextContext];
 
 interface ComboBoxInnerProps<T extends object> {
-  props: ComboBoxProps<T>,
+  props: ComboBoxProps<T, SelectionMode>,
   collection: Collection<Node<T>>,
   comboBoxRef: RefObject<HTMLDivElement | null>
 }
diff --git a/packages/react-aria-components/stories/ComboBox.stories.tsx b/packages/react-aria-components/stories/ComboBox.stories.tsx
index 4aa528a18bb..9c256300c77 100644
--- a/packages/react-aria-components/stories/ComboBox.stories.tsx
+++ b/packages/react-aria-components/stories/ComboBox.stories.tsx
@@ -10,12 +10,13 @@
  * governing permissions and limitations under the License.
  */
 
-import {Button, Collection, ComboBox, ComboBoxProps, Input, Label, ListBox, ListLayout, Popover, useFilter, Virtualizer} from 'react-aria-components';
+import {Button, Collection, ComboBox, ComboBoxProps, ComboBoxStateContext, Input, Label, ListBox, ListLayout, Popover, useFilter, Virtualizer} from 'react-aria-components';
 import {ListBoxLoadMoreItem} from '../src/ListBox';
 import {LoadingSpinner, MyListBoxItem} from './utils';
 import {Meta, StoryFn, StoryObj} from '@storybook/react';
 import React, {JSX, useMemo, useState} from 'react';
 import styles from '../example/index.css';
+import {Tag, TagGroup} from 'vanilla-starter/TagGroup';
 import {useAsyncList} from 'react-stately';
 import './styles.css';
 
@@ -389,3 +390,101 @@ export const ComboBoxListBoxItemWithAriaLabel: ComboBoxStory = () => (
     </Popover>
   </ComboBox>
 );
+
+export const MultiSelectComboBox: ComboBoxStory = () => (
+  <ComboBox allowsEmptyCollection selectionMode="multiple" defaultItems={usStateOptions}>
+    <Label style={{display: 'block'}}>Test</Label>
+    <div style={{display: 'flex'}}>
+      <Input placeholder="Select an item" />
+      <Button>
+        <span aria-hidden="true" style={{padding: '0 2px'}}>▼</span>
+      </Button>
+    </div>
+    <ComboBoxStateContext.Consumer>
+      {state => state && (
+        <TagGroup
+          aria-label="Selected states"
+          items={state.selectedItems.map(item => item.value)}
+          renderEmptyState={() => 'No selected items'}
+          onRemove={(keys) => {
+            // Remove keys from ComboBox state.
+            if (Array.isArray(state.value)) {
+              state.setValue(state.value.filter(k => !keys.has(k)));
+            }
+          }}>
+          {item => <Tag>{item.name}</Tag>}
+        </TagGroup>
+      )}
+    </ComboBoxStateContext.Consumer>
+    <Popover placement="bottom end">
+      <ListBox<{name: string}>
+        renderEmptyState={renderEmptyState}
+        data-testid="combo-box-list-box"
+        className={styles.menu}>
+        {item => <MyListBoxItem>{item.name}</MyListBoxItem>}
+      </ListBox>
+    </Popover>
+  </ComboBox>
+);
+
+const usStateOptions = [
+  {id: 'AL', name: 'Alabama'},
+  {id: 'AK', name: 'Alaska'},
+  {id: 'AS', name: 'American Samoa'},
+  {id: 'AZ', name: 'Arizona'},
+  {id: 'AR', name: 'Arkansas'},
+  {id: 'CA', name: 'California'},
+  {id: 'CO', name: 'Colorado'},
+  {id: 'CT', name: 'Connecticut'},
+  {id: 'DE', name: 'Delaware'},
+  {id: 'DC', name: 'District Of Columbia'},
+  {id: 'FM', name: 'Federated States Of Micronesia'},
+  {id: 'FL', name: 'Florida'},
+  {id: 'GA', name: 'Georgia'},
+  {id: 'GU', name: 'Guam'},
+  {id: 'HI', name: 'Hawaii'},
+  {id: 'ID', name: 'Idaho'},
+  {id: 'IL', name: 'Illinois'},
+  {id: 'IN', name: 'Indiana'},
+  {id: 'IA', name: 'Iowa'},
+  {id: 'KS', name: 'Kansas'},
+  {id: 'KY', name: 'Kentucky'},
+  {id: 'LA', name: 'Louisiana'},
+  {id: 'ME', name: 'Maine'},
+  {id: 'MH', name: 'Marshall Islands'},
+  {id: 'MD', name: 'Maryland'},
+  {id: 'MA', name: 'Massachusetts'},
+  {id: 'MI', name: 'Michigan'},
+  {id: 'MN', name: 'Minnesota'},
+  {id: 'MS', name: 'Mississippi'},
+  {id: 'MO', name: 'Missouri'},
+  {id: 'MT', name: 'Montana'},
+  {id: 'NE', name: 'Nebraska'},
+  {id: 'NV', name: 'Nevada'},
+  {id: 'NH', name: 'New Hampshire'},
+  {id: 'NJ', name: 'New Jersey'},
+  {id: 'NM', name: 'New Mexico'},
+  {id: 'NY', name: 'New York'},
+  {id: 'NC', name: 'North Carolina'},
+  {id: 'ND', name: 'North Dakota'},
+  {id: 'MP', name: 'Northern Mariana Islands'},
+  {id: 'OH', name: 'Ohio'},
+  {id: 'OK', name: 'Oklahoma'},
+  {id: 'OR', name: 'Oregon'},
+  {id: 'PW', name: 'Palau'},
+  {id: 'PA', name: 'Pennsylvania'},
+  {id: 'PR', name: 'Puerto Rico'},
+  {id: 'RI', name: 'Rhode Island'},
+  {id: 'SC', name: 'South Carolina'},
+  {id: 'SD', name: 'South Dakota'},
+  {id: 'TN', name: 'Tennessee'},
+  {id: 'TX', name: 'Texas'},
+  {id: 'UT', name: 'Utah'},
+  {id: 'VT', name: 'Vermont'},
+  {id: 'VI', name: 'Virgin Islands'},
+  {id: 'VA', name: 'Virginia'},
+  {id: 'WA', name: 'Washington'},
+  {id: 'WV', name: 'West Virginia'},
+  {id: 'WI', name: 'Wisconsin'},
+  {id: 'WY', name: 'Wyoming'}
+];

From 92ccc6d3f270295ab79dddac7c3e3188e2112b39 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Tue, 27 Jan 2026 09:31:05 -0800
Subject: [PATCH 02/11] Add docs example

---
 .../dev/s2-docs/pages/react-aria/ComboBox.mdx | 104 +++++++++++++++++-
 1 file changed, 102 insertions(+), 2 deletions(-)

diff --git a/packages/dev/s2-docs/pages/react-aria/ComboBox.mdx b/packages/dev/s2-docs/pages/react-aria/ComboBox.mdx
index 93afe017da9..f039e21264e 100644
--- a/packages/dev/s2-docs/pages/react-aria/ComboBox.mdx
+++ b/packages/dev/s2-docs/pages/react-aria/ComboBox.mdx
@@ -20,7 +20,7 @@ export const description = 'Combines a text input with a listbox, allowing users
 <PageDescription>{docs.exports.ComboBox.description}</PageDescription>
 
 <ExampleSwitcher>
-  ```tsx render docs={vanillaDocs.exports.ComboBox} links={vanillaDocs.links} props={['label', 'isDisabled']} initialProps={{label: 'Favorite Animal', placeholder: 'Select an animal'}} type="vanilla" files={["starters/docs/src/ComboBox.tsx", "starters/docs/src/ComboBox.css"]}
+  ```tsx render docs={vanillaDocs.exports.ComboBox} links={vanillaDocs.links} props={['label', 'selectionMode', 'isDisabled']} initialProps={{label: 'Favorite Animal', placeholder: 'Select an animal'}} type="vanilla" files={["starters/docs/src/ComboBox.tsx", "starters/docs/src/ComboBox.css"]}
   "use client";
   import {ComboBox, ComboBoxItem} from 'vanilla-starter/ComboBox';
 
@@ -34,7 +34,7 @@ export const description = 'Combines a text input with a listbox, allowing users
   </ComboBox>
   ```
 
-  ```tsx render docs={vanillaDocs.exports.ComboBox} links={vanillaDocs.links} props={['label', 'isDisabled']} initialProps={{label: 'Favorite Animal', placeholder: 'Select an animal'}} type="tailwind" files={["starters/tailwind/src/ComboBox.tsx"]}
+  ```tsx render docs={vanillaDocs.exports.ComboBox} links={vanillaDocs.links} props={['label', 'selectionMode', 'isDisabled']} initialProps={{label: 'Favorite Animal', placeholder: 'Select an animal'}} type="tailwind" files={["starters/tailwind/src/ComboBox.tsx"]}
   "use client";
   import {ComboBox, ComboBoxItem} from 'tailwind-starter/ComboBox';
 
@@ -142,6 +142,106 @@ function Example() {
 }
 ```
 
+### Multiple selection
+
+Use `ComboBoxStateContext` to render the selected items as a [TagGroup](TagGroup).
+
+```tsx render
+"use client";
+import {ComboBox, ComboBoxStateContext, Input} from 'react-aria-components';
+import {ComboBoxListBox, ComboBoxItem} from 'vanilla-starter/ComboBox';
+import {Label, FieldButton} from 'vanilla-starter/Form';
+import {Popover} from 'vanilla-starter/Popover';
+import {Tag, TagGroup} from 'vanilla-starter/TagGroup';
+import {ChevronDown} from 'lucide-react';
+
+/*- begin collapse -*/
+const states = [
+  {id: 'AL', name: 'Alabama'},
+  {id: 'AK', name: 'Alaska'},
+  {id: 'AZ', name: 'Arizona'},
+  {id: 'AR', name: 'Arkansas'},
+  {id: 'CA', name: 'California'},
+  {id: 'CO', name: 'Colorado'},
+  {id: 'CT', name: 'Connecticut'},
+  {id: 'DE', name: 'Delaware'},
+  {id: 'DC', name: 'District of Columbia'},
+  {id: 'FL', name: 'Florida'},
+  {id: 'GA', name: 'Georgia'},
+  {id: 'HI', name: 'Hawaii'},
+  {id: 'ID', name: 'Idaho'},
+  {id: 'IL', name: 'Illinois'},
+  {id: 'IN', name: 'Indiana'},
+  {id: 'IA', name: 'Iowa'},
+  {id: 'KS', name: 'Kansas'},
+  {id: 'KY', name: 'Kentucky'},
+  {id: 'LA', name: 'Louisiana'},
+  {id: 'ME', name: 'Maine'},
+  {id: 'MD', name: 'Maryland'},
+  {id: 'MA', name: 'Massachusetts'},
+  {id: 'MI', name: 'Michigan'},
+  {id: 'MN', name: 'Minnesota'},
+  {id: 'MS', name: 'Mississippi'},
+  {id: 'MO', name: 'Missouri'},
+  {id: 'MT', name: 'Montana'},
+  {id: 'NE', name: 'Nebraska'},
+  {id: 'NV', name: 'Nevada'},
+  {id: 'NH', name: 'New Hampshire'},
+  {id: 'NJ', name: 'New Jersey'},
+  {id: 'NM', name: 'New Mexico'},
+  {id: 'NY', name: 'New York'},
+  {id: 'NC', name: 'North Carolina'},
+  {id: 'ND', name: 'North Dakota'},
+  {id: 'OH', name: 'Ohio'},
+  {id: 'OK', name: 'Oklahoma'},
+  {id: 'OR', name: 'Oregon'},
+  {id: 'PA', name: 'Pennsylvania'},
+  {id: 'RI', name: 'Rhode Island'},
+  {id: 'SC', name: 'South Carolina'},
+  {id: 'SD', name: 'South Dakota'},
+  {id: 'TN', name: 'Tennessee'},
+  {id: 'TX', name: 'Texas'},
+  {id: 'UT', name: 'Utah'},
+  {id: 'VT', name: 'Vermont'},
+  {id: 'VA', name: 'Virginia'},
+  {id: 'WA', name: 'Washington'},
+  {id: 'WV', name: 'West Virginia'},
+  {id: 'WI', name: 'Wisconsin'},
+  {id: 'WY', name: 'Wyoming'}
+];
+/*- end collapse -*/
+
+<ComboBox selectionMode="multiple">
+  <Label>States</Label>
+  <div className="combobox-field">
+    <Input className="react-aria-Input inset" placeholder="Select a state" />
+    <FieldButton><ChevronDown /></FieldButton>
+  </div>
+  <ComboBoxStateContext.Consumer>
+    {state => state && (
+      <TagGroup
+        aria-label="Selected states"
+        style={{marginTop: 8}}
+        items={state.selectedItems}
+        renderEmptyState={() => 'No selected items'}
+        onRemove={(keys) => {
+          // Remove keys from Select state.
+          if (Array.isArray(state.value)) {
+            state.setValue(state.value.filter(k => !keys.has(k)));
+          }
+        }}>
+        {item => <Tag>{item.value.name}</Tag>}
+      </TagGroup>
+    )}
+  </ComboBoxStateContext.Consumer>
+  <Popover hideArrow className="combobox-popover">
+    <ComboBoxListBox items={states}>
+      {state => <ComboBoxItem>{state.name}</ComboBoxItem>}
+    </ComboBoxListBox>
+  </Popover>
+</ComboBox>
+```
+
 ### Input value
 
 Use the `inputValue` or `defaultInputValue` prop to set the value of the input field. By default, the value will be reverted to the selected item on blur. Set the `allowsCustomValue` prop to enable entering values that are not in the list.

From c247e8fff6c6d1f3e96c2520b2b277b20541c968 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Tue, 27 Jan 2026 09:31:21 -0800
Subject: [PATCH 03/11] Render multiple hidden inputs for multi-select

---
 .../react-aria-components/src/ComboBox.tsx     | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/packages/react-aria-components/src/ComboBox.tsx b/packages/react-aria-components/src/ComboBox.tsx
index 53f3da93dca..5c4afe161e8 100644
--- a/packages/react-aria-components/src/ComboBox.tsx
+++ b/packages/react-aria-components/src/ComboBox.tsx
@@ -29,14 +29,14 @@ import {CollectionBuilder} from '@react-aria/collections';
 import {FieldErrorContext} from './FieldError';
 import {filterDOMProps, useResizeObserver} from '@react-aria/utils';
 import {FormContext} from './Form';
-import {forwardRefType, GlobalDOMAttributes, RefObject} from '@react-types/shared';
+import {forwardRefType, GlobalDOMAttributes, Key, RefObject} from '@react-types/shared';
 import {GroupContext} from './Group';
 import {InputContext} from './Input';
 import {LabelContext} from './Label';
 import {ListBoxContext, ListStateContext} from './ListBox';
 import {OverlayTriggerStateContext} from './Dialog';
 import {PopoverContext} from './Popover';
-import React, {createContext, ForwardedRef, forwardRef, useCallback, useMemo, useRef, useState} from 'react';
+import React, {createContext, ForwardedRef, forwardRef, ReactElement, useCallback, useMemo, useRef, useState} from 'react';
 import {TextContext} from './Text';
 
 type SelectionMode = 'single' | 'multiple';
@@ -206,6 +206,18 @@ function ComboBoxInner<T extends object>({props, collection, comboBoxRef: ref}:
   let DOMProps = filterDOMProps(props, {global: true});
   delete DOMProps.id;
 
+  let inputs: ReactElement[] = [];
+  if (name && formValue === 'key') {
+    let values: (Key | null)[] = Array.isArray(state.value) ? state.value : [state.value];
+    if (values.length === 0) {
+      values = [null];
+    }
+
+    inputs = values.map((value, i) => (
+      <input key={i} type="hidden" name={name} form={props.form} value={value ?? ''} />
+    ));
+  }
+
   return (
     <Provider
       values={[
@@ -245,7 +257,7 @@ function ComboBoxInner<T extends object>({props, collection, comboBoxRef: ref}:
         data-disabled={props.isDisabled || undefined}
         data-invalid={validation.isInvalid || undefined}
         data-required={props.isRequired || undefined} />
-      {name && formValue === 'key' && <input type="hidden" name={name} form={props.form} value={state.selectedKey ?? ''} />}
+      {inputs}
     </Provider>
   );
 }

From 9b6ecfa3ee694ef7d861edb02ab09ee66e81d14a Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Tue, 27 Jan 2026 09:36:59 -0800
Subject: [PATCH 04/11] Add a couple tests

---
 .../test/ComboBox.test.js                     | 50 ++++++++++++++++++-
 1 file changed, 49 insertions(+), 1 deletion(-)

diff --git a/packages/react-aria-components/test/ComboBox.test.js b/packages/react-aria-components/test/ComboBox.test.js
index 4e581397905..8b21e43f01f 100644
--- a/packages/react-aria-components/test/ComboBox.test.js
+++ b/packages/react-aria-components/test/ComboBox.test.js
@@ -11,7 +11,7 @@
  */
 
 import {act} from '@testing-library/react';
-import {Button, ComboBox, ComboBoxContext, FieldError, Header, Input, Label, ListBox, ListBoxItem, ListBoxLoadMoreItem, ListBoxSection, ListLayout, Popover, Text, Virtualizer} from '../';
+import {Button, ComboBox, ComboBoxContext, FieldError, Form, Header, Input, Label, ListBox, ListBoxItem, ListBoxLoadMoreItem, ListBoxSection, ListLayout, Popover, Text, Virtualizer} from '../';
 import {fireEvent, pointerMap, render, within} from '@react-spectrum/test-utils-internal';
 import React, {useState} from 'react';
 import {User} from '@react-aria/test-utils';
@@ -630,4 +630,52 @@ describe('ComboBox', () => {
     expect(tree.queryByRole('listbox')).toBeNull();
     expect(comboboxTester.combobox).toHaveValue('Apple');
   });
+
+  it('should support multiple selection', async () => {
+    let onChange = jest.fn();
+    let {container, getByTestId} = render(
+      <Form data-testid="form">
+        <TestComboBox name="select" selectionMode="multiple" defaultInputValue="" onChange={onChange} />
+      </Form>
+    );
+    let comboboxTester = testUtilUser.createTester('ComboBox', {root: container});
+
+    expect(comboboxTester.combobox).toHaveValue('');
+    await comboboxTester.open();
+
+    let listbox = comboboxTester.listbox;
+    expect(listbox).toHaveAttribute('aria-multiselectable', 'true');
+
+    let options = comboboxTester.options();
+    expect(options).toHaveLength(3);
+
+    await user.click(options[0]);
+    expect(options[0]).toHaveAttribute('aria-selected', 'true');
+    expect(comboboxTester.combobox).toHaveValue('');
+    expect(comboboxTester.listbox).toBeInTheDocument();
+    await user.click(options[1]);
+    expect(options[1]).toHaveAttribute('aria-selected', 'true');
+    expect(comboboxTester.combobox).toHaveValue('');
+    expect(comboboxTester.listbox).toBeInTheDocument();
+    await comboboxTester.close();
+
+    expect(onChange).toHaveBeenCalledTimes(2);
+    expect(onChange).toHaveBeenLastCalledWith(['1', '2']);
+
+    let formData = new FormData(getByTestId('form'));
+    expect(formData.getAll('select')).toEqual(['1', '2']);
+  });
+
+  it('should support controlled multi-selection', async () => {
+    let {container} = render(<TestComboBox selectionMode="multiple" defaultInputValue={undefined} value={['2', '3']} />);
+
+    let comboboxTester = testUtilUser.createTester('ComboBox', {root: container});
+    expect(comboboxTester.combobox).toHaveValue('');
+    await comboboxTester.open();
+
+    let options = comboboxTester.options();
+    expect(options[0]).toHaveAttribute('aria-selected', 'false');
+    expect(options[1]).toHaveAttribute('aria-selected', 'true');
+    expect(options[2]).toHaveAttribute('aria-selected', 'true');
+  });
 });

From b83c5dfe8c67b407ad779527e9a000569b1c9eb3 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Wed, 28 Jan 2026 21:31:23 -0800
Subject: [PATCH 05/11] Omit from RSP

---
 packages/@react-spectrum/s2/src/ComboBox.tsx  | 5 +++--
 packages/@react-types/combobox/src/index.d.ts | 5 +++--
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/packages/@react-spectrum/s2/src/ComboBox.tsx b/packages/@react-spectrum/s2/src/ComboBox.tsx
index d3cd25f882f..36e607cd2a7 100644
--- a/packages/@react-spectrum/s2/src/ComboBox.tsx
+++ b/packages/@react-spectrum/s2/src/ComboBox.tsx
@@ -33,7 +33,7 @@ import {
   SectionProps,
   Virtualizer
 } from 'react-aria-components';
-import {AsyncLoadable, GlobalDOMAttributes, HelpTextProps, LoadingState, SpectrumLabelableProps} from '@react-types/shared';
+import {AsyncLoadable, GlobalDOMAttributes, HelpTextProps, LoadingState, SingleSelection, SpectrumLabelableProps} from '@react-types/shared';
 import {AvatarContext} from './Avatar';
 import {BaseCollection, CollectionNode, createLeafComponent} from '@react-aria/collections';
 import {baseColor, focusRing, space, style} from '../style' with {type: 'macro'};
@@ -79,7 +79,8 @@ export interface ComboboxStyleProps {
   size?: 'S' | 'M' | 'L' | 'XL'
 }
 export interface ComboBoxProps<T extends object> extends
-  Omit<AriaComboBoxProps<T>, 'children' | 'style' | 'className' | 'render' | 'defaultFilter' | 'allowsEmptyCollection' | 'isTriggerUpWhenOpen' | keyof GlobalDOMAttributes>,
+  Omit<AriaComboBoxProps<T>, 'children' | 'style' | 'className' | 'render' | 'defaultFilter' | 'allowsEmptyCollection' | 'isTriggerUpWhenOpen' | 'selectionMode' | 'selectedKey' | 'defaultSelectedKey' | 'onSelectionChange' | 'value' | 'defaultValue' | 'onChange' | keyof GlobalDOMAttributes>,
+  Omit<SingleSelection, 'disallowEmptySelection'>,
   ComboboxStyleProps,
   StyleProps,
   SpectrumLabelableProps,
diff --git a/packages/@react-types/combobox/src/index.d.ts b/packages/@react-types/combobox/src/index.d.ts
index 295b010d260..3eefa51123e 100644
--- a/packages/@react-types/combobox/src/index.d.ts
+++ b/packages/@react-types/combobox/src/index.d.ts
@@ -23,6 +23,7 @@ import {
   Key,
   LabelableProps,
   LoadingState,
+  SingleSelection,
   SpectrumFieldValidation,
   SpectrumLabelableProps,
   SpectrumTextInputBase,
@@ -83,7 +84,7 @@ export interface ComboBoxProps<T, M extends SelectionMode = 'single'> extends Co
   /** Handler that is called when the ComboBox input value changes. */
   onInputChange?: (value: string) => void,
   /** Whether the ComboBox allows a non-item matching input value to be set. */
-  allowsCustomValue?: boolean,
+allowsCustomValue?: boolean,
   // /**
   //  * Whether the Combobox should only suggest matching options or autocomplete the field with the nearest matching option.
   //  * @default 'suggest'
@@ -101,7 +102,7 @@ export interface AriaComboBoxProps<T, M extends SelectionMode = 'single'> extend
   shouldFocusWrap?: boolean
 }
 
-export interface SpectrumComboBoxProps<T> extends SpectrumTextInputBase, Omit<AriaComboBoxProps<T>, 'menuTrigger' | 'isInvalid' | 'validationState'>, SpectrumFieldValidation<ComboBoxValidationValue>, SpectrumLabelableProps, StyleProps, Omit<AsyncLoadable, 'isLoading'> {
+export interface SpectrumComboBoxProps<T> extends SpectrumTextInputBase, Omit<AriaComboBoxProps<T>, 'menuTrigger' | 'isInvalid' | 'validationState' | 'selectionMode' | 'selectedKey' | 'defaultSelectedKey' | 'onSelectionChange' | 'value' | 'defaultValue' | 'onChange'>, Omit<SingleSelection, 'disallowEmptySelection'>, SpectrumFieldValidation<ComboBoxValidationValue>, SpectrumLabelableProps, StyleProps, Omit<AsyncLoadable, 'isLoading'> {
   /**
    * The interaction required to display the ComboBox menu. Note that this prop has no effect on the mobile ComboBox experience.
    * @default 'input'

From fa9a6315ece75dc7502cc63c0db6bfed08009090 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Thu, 29 Jan 2026 09:24:32 -0800
Subject: [PATCH 06/11] Add more tests

---
 .../@react-aria/combobox/src/useComboBox.ts   |  5 +-
 .../combobox/src/useComboBoxState.ts          | 11 ++--
 .../dev/s2-docs/pages/react-aria/ComboBox.mdx |  4 +-
 .../test/ComboBox.test.js                     | 56 +++++++++++++++++--
 4 files changed, 63 insertions(+), 13 deletions(-)

diff --git a/packages/@react-aria/combobox/src/useComboBox.ts b/packages/@react-aria/combobox/src/useComboBox.ts
index 946cef824db..0dbb685e2b4 100644
--- a/packages/@react-aria/combobox/src/useComboBox.ts
+++ b/packages/@react-aria/combobox/src/useComboBox.ts
@@ -158,7 +158,7 @@ export function useComboBox<T, M extends SelectionMode = 'single'>(props: AriaCo
         break;
       case 'Escape':
         if (
-          state.selectedKey !== null ||
+          !state.selectionManager.isEmpty ||
           state.inputValue === '' ||
           props.allowsCustomValue
         ) {
@@ -220,7 +220,7 @@ export function useComboBox<T, M extends SelectionMode = 'single'>(props: AriaCo
     [privateValidationStateProp]: state
   }, inputRef);
 
-  useFormReset(inputRef, state.defaultSelectedKey, state.setSelectedKey);
+  useFormReset(inputRef, state.defaultValue, state.setValue);
   
   // Press handlers for the ComboBox button
   let onPress = (e: PressEvent) => {
@@ -332,6 +332,7 @@ export function useComboBox<T, M extends SelectionMode = 'single'>(props: AriaCo
   });
 
   // Announce when a selection occurs for VoiceOver. Other screen readers typically do this automatically.
+  // TODO: do we need to do this for multi-select?
   let lastSelectedKey = useRef(state.selectedKey);
   useEffect(() => {
     if (isAppleDevice() && state.isFocused && state.selectedItem && state.selectedKey !== lastSelectedKey.current) {
diff --git a/packages/@react-stately/combobox/src/useComboBoxState.ts b/packages/@react-stately/combobox/src/useComboBoxState.ts
index 6e8a5b08016..c0485953aee 100644
--- a/packages/@react-stately/combobox/src/useComboBoxState.ts
+++ b/packages/@react-stately/combobox/src/useComboBoxState.ts
@@ -313,13 +313,13 @@ export function useComboBoxState<T extends object, M extends SelectionMode = 'si
 
       // Set value to null when the user clears the input.
       // If controlled, this is the application developer's responsibility.
-      if (inputValue === '' && (props.inputValue === undefined || value === undefined)) {
+      if (selectionMode === 'single' && inputValue === '' && (props.inputValue === undefined || value === undefined)) {
         setValue(null);
       }
     }
 
-    // If the selectedKey changed, update the input value.
-    // Do nothing if both inputValue and selectedKey are controlled.
+    // If the value changed, update the input value.
+    // Do nothing if both inputValue and value are controlled.
     // In this case, it's the user's responsibility to update inputValue in onSelectionChange.
     if (
       displayValue !== lastValueRef.current &&
@@ -371,6 +371,7 @@ export function useComboBoxState<T extends object, M extends SelectionMode = 'si
     // If multiple things are controlled, call onSelectionChange
     if (value !== undefined && props.inputValue !== undefined) {
       props.onSelectionChange?.(selectedKey);
+      props.onChange?.(displayValue);
 
       // Stop menu from reopening from useEffect
       let itemText = selectedKey != null ? collection.getItem(selectedKey)?.textValue ?? '' : '';
@@ -397,7 +398,7 @@ export function useComboBoxState<T extends object, M extends SelectionMode = 'si
     if (triggerState.isOpen && selectionManager.focusedKey != null) {
       // Reset inputValue and close menu here if the selected key is already the focused key. Otherwise
       // fire onSelectionChange to allow the application to control the closing.
-      if (selectedKey === selectionManager.focusedKey) {
+      if (selectionManager.isSelected(selectionManager.focusedKey)) {
         commitSelection();
       } else {
         selectionManager.select(selectionManager.focusedKey);
@@ -439,7 +440,7 @@ export function useComboBoxState<T extends object, M extends SelectionMode = 'si
     }
   }, [triggerState.isOpen, originalCollection, filteredCollection, showAllItems, lastCollection]);
 
-  let defaultSelectedKey = props.defaultSelectedKey ?? (props.selectionMode === 'single' ? initialValue as Key : null);
+  let defaultSelectedKey = props.defaultSelectedKey ?? (selectionMode === 'single' ? initialValue as Key : null);
 
   return {
     ...validation,
diff --git a/packages/dev/s2-docs/pages/react-aria/ComboBox.mdx b/packages/dev/s2-docs/pages/react-aria/ComboBox.mdx
index f039e21264e..fac5e7e627e 100644
--- a/packages/dev/s2-docs/pages/react-aria/ComboBox.mdx
+++ b/packages/dev/s2-docs/pages/react-aria/ComboBox.mdx
@@ -217,6 +217,7 @@ const states = [
     <Input className="react-aria-Input inset" placeholder="Select a state" />
     <FieldButton><ChevronDown /></FieldButton>
   </div>
+  {/*- begin highlight -*/}
   <ComboBoxStateContext.Consumer>
     {state => state && (
       <TagGroup
@@ -225,7 +226,7 @@ const states = [
         items={state.selectedItems}
         renderEmptyState={() => 'No selected items'}
         onRemove={(keys) => {
-          // Remove keys from Select state.
+          // Remove keys from ComboBox state.
           if (Array.isArray(state.value)) {
             state.setValue(state.value.filter(k => !keys.has(k)));
           }
@@ -234,6 +235,7 @@ const states = [
       </TagGroup>
     )}
   </ComboBoxStateContext.Consumer>
+  {/*- end highlight -*/}
   <Popover hideArrow className="combobox-popover">
     <ComboBoxListBox items={states}>
       {state => <ComboBoxItem>{state.name}</ComboBoxItem>}
diff --git a/packages/react-aria-components/test/ComboBox.test.js b/packages/react-aria-components/test/ComboBox.test.js
index ccb9df941ec..57d50ee32c5 100644
--- a/packages/react-aria-components/test/ComboBox.test.js
+++ b/packages/react-aria-components/test/ComboBox.test.js
@@ -258,7 +258,7 @@ describe('ComboBox', () => {
   });
 
   it('should support formValue', () => {
-    let {getByRole, rerender} = render(<TestComboBox name="test" selectedKey="2" />);
+    let {getByRole, rerender} = render(<TestComboBox name="test" value="2" />);
     let input = getByRole('combobox');
     expect(input).not.toHaveAttribute('name');
     expect(input).toHaveValue('Dog');
@@ -266,7 +266,7 @@ describe('ComboBox', () => {
     expect(hiddenInput).toHaveAttribute('name', 'test');
     expect(hiddenInput).toHaveValue('2');
 
-    rerender(<TestComboBox name="test" formValue="text" selectedKey="2" />);
+    rerender(<TestComboBox name="test" formValue="text" value="2" />);
     expect(input).toHaveAttribute('name', 'test');
     expect(document.querySelector('input[type=hidden]')).toBeNull();
   });
@@ -274,7 +274,7 @@ describe('ComboBox', () => {
   it('should support form reset', async () => {
     const tree = render(
       <form>
-        <ComboBox defaultSelectedKey="2" name="combobox">
+        <ComboBox defaultValue="2" name="combobox">
           <Label>Favorite Animal</Label>
           <Input />
           <Button />
@@ -641,7 +641,8 @@ describe('ComboBox', () => {
     let onChange = jest.fn();
     let {container, getByTestId} = render(
       <Form data-testid="form">
-        <TestComboBox name="select" selectionMode="multiple" defaultInputValue="" onChange={onChange} />
+        <TestComboBox name="combobox" selectionMode="multiple" defaultInputValue="" onChange={onChange} />
+        <input type="reset" />
       </Form>
     );
     let comboboxTester = testUtilUser.createTester('ComboBox', {root: container});
@@ -669,7 +670,12 @@ describe('ComboBox', () => {
     expect(onChange).toHaveBeenLastCalledWith(['1', '2']);
 
     let formData = new FormData(getByTestId('form'));
-    expect(formData.getAll('select')).toEqual(['1', '2']);
+    expect(formData.getAll('combobox')).toEqual(['1', '2']);
+
+    await user.click(document.querySelector('input[type="reset"]'));
+    expect(comboboxTester.combobox).toHaveValue('');
+    formData = new FormData(getByTestId('form'));
+    expect(formData.getAll('combobox')).toEqual(['']);
   });
 
   it('should support controlled multi-selection', async () => {
@@ -684,4 +690,44 @@ describe('ComboBox', () => {
     expect(options[1]).toHaveAttribute('aria-selected', 'true');
     expect(options[2]).toHaveAttribute('aria-selected', 'true');
   });
+
+  it('should support controlled multi-selection with both inputValue and value controlled', async () => {
+    let onChange = jest.fn();
+    let onInputChange = jest.fn();
+    let {container} = render(<TestComboBox selectionMode="multiple" defaultInputValue={undefined} inputValue="C" onInputChange={onInputChange} value={['2', '3']} onChange={onChange} />);
+
+    let comboboxTester = testUtilUser.createTester('ComboBox', {root: container});
+    let combobox = comboboxTester.combobox;
+    expect(combobox).toHaveValue('C');
+    await comboboxTester.open();
+
+    await user.keyboard('a');
+
+    act(() => {
+      jest.runAllTimers();
+    });
+
+    expect(combobox).toHaveValue('C');
+    expect(onInputChange).toHaveBeenCalledTimes(1);
+    expect(onInputChange).toHaveBeenCalledWith('Ca');
+    expect(onChange).not.toHaveBeenCalled();
+
+    await user.keyboard('{Enter}');
+
+    expect(combobox).toHaveValue('C');
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange).toHaveBeenCalledWith(['2', '3']);
+  });
+
+  it('should support multi-select with custom value', async () => {
+    let {container} = render(<TestComboBox selectionMode="multiple" allowsCustomValue />);
+    let comboboxTester = testUtilUser.createTester('ComboBox', {root: container});
+
+    await user.tab();
+    await user.keyboard('Test');
+    expect(comboboxTester.combobox).toHaveValue('Test');
+
+    await user.tab();
+    expect(comboboxTester.combobox).toHaveValue('Test');
+  });
 });

From 0a5778968d71eef08c07af06b20bd3cc30675646 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Wed, 4 Feb 2026 12:05:26 -0800
Subject: [PATCH 07/11] Fix tests

---
 packages/@react-stately/combobox/src/useComboBoxState.ts | 4 +++-
 packages/react-aria-components/test/ComboBox.test.js     | 1 +
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/@react-stately/combobox/src/useComboBoxState.ts b/packages/@react-stately/combobox/src/useComboBoxState.ts
index c0485953aee..308c22e0fa7 100644
--- a/packages/@react-stately/combobox/src/useComboBoxState.ts
+++ b/packages/@react-stately/combobox/src/useComboBoxState.ts
@@ -82,6 +82,8 @@ export interface ComboBoxStateOptions<T, M extends SelectionMode = 'single'> ext
   shouldCloseOnBlur?: boolean
 }
 
+const EMPTY_VALUE: Key[] = [];
+
 /**
  * Provides state management for a combo box component. Handles building a collection
  * of items from props and manages the option selection state of the combo box. In addition, it tracks the input value,
@@ -361,7 +363,7 @@ export function useComboBoxState<T extends object, M extends SelectionMode = 'si
   };
 
   let commitCustomValue = () => {
-    let value = selectionMode === 'multiple' ? [] : null;
+    let value = selectionMode === 'multiple' ? EMPTY_VALUE : null;
     lastValueRef.current = value as any;
     setValue(value);
     closeMenu();
diff --git a/packages/react-aria-components/test/ComboBox.test.js b/packages/react-aria-components/test/ComboBox.test.js
index 67f3ee7d4dd..68c09257d6e 100644
--- a/packages/react-aria-components/test/ComboBox.test.js
+++ b/packages/react-aria-components/test/ComboBox.test.js
@@ -711,6 +711,7 @@ describe('ComboBox', () => {
   });
 
   it('should support multi-select with custom value', async () => {
+    // allowsCustomValue doesn't really make sense to use with multi-selection, but test it anyway.
     let {container} = render(<TestComboBox selectionMode="multiple" allowsCustomValue />);
     let comboboxTester = testUtilUser.createTester('ComboBox', {root: container});
 

From e3621fb05d289d749748343ee0bc899e4f1a4db8 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Thu, 5 Feb 2026 16:49:58 -0800
Subject: [PATCH 08/11] Add ComboBoxValue and update docs

---
 .../dev/s2-docs/pages/react-aria/ComboBox.mdx | 115 +++++++++---------
 .../s2-docs/pages/react-aria/selection.mdx    |  31 +++--
 packages/dev/s2-docs/src/PropTable.tsx        |   2 +-
 .../react-aria-components/src/ComboBox.tsx    |  62 +++++++++-
 packages/react-aria-components/src/index.ts   |   4 +-
 starters/docs/src/ComboBox.css                |   5 +
 starters/docs/src/ComboBox.tsx                |  10 +-
 starters/docs/src/Select.tsx                  |   9 +-
 starters/tailwind/src/ComboBox.tsx            |   8 +-
 starters/tailwind/src/Select.tsx              |   6 +-
 10 files changed, 167 insertions(+), 85 deletions(-)

diff --git a/packages/dev/s2-docs/pages/react-aria/ComboBox.mdx b/packages/dev/s2-docs/pages/react-aria/ComboBox.mdx
index fac5e7e627e..b106693150e 100644
--- a/packages/dev/s2-docs/pages/react-aria/ComboBox.mdx
+++ b/packages/dev/s2-docs/pages/react-aria/ComboBox.mdx
@@ -107,48 +107,13 @@ function Example() {
 }
 ```
 
-## Selection
+### TagGroup
 
-Use the `defaultSelectedKey` or `selectedKey` prop to set the selected item. The selected key corresponds to the `id` prop of an item. Items can be disabled with the `isDisabled` prop. See the [selection guide](selection?component=ComboBox#single-selection) for more details.
+Use the `ComboBoxValue` render prop function to display the selected items as a [TagGroup](TagGroup).
 
 ```tsx render
 "use client";
-import {ComboBox, ComboBoxItem} from 'vanilla-starter/ComboBox';
-import {useState} from 'react';
-import type {Key} from 'react-aria-components';
-
-function Example() {
-  let [animal, setAnimal] = useState<Key | null>("bison");
-
-  return (
-    <div>
-      <ComboBox
-        label="Favorite Animal"
-        placeholder="Select an animal"
-        /*- begin highlight -*/
-        selectedKey={animal}
-        onSelectionChange={setAnimal}>
-        {/*- end highlight -*/}
-        <ComboBoxItem id="koala">Koala</ComboBoxItem>
-        <ComboBoxItem id="kangaroo">Kangaroo</ComboBoxItem>
-        <ComboBoxItem id="platypus" isDisabled>Platypus</ComboBoxItem>
-        <ComboBoxItem id="eagle">Bald Eagle</ComboBoxItem>
-        <ComboBoxItem id="bison">Bison</ComboBoxItem>
-        <ComboBoxItem id="skunk">Skunk</ComboBoxItem>
-      </ComboBox>
-      <p>Current selection: {animal}</p>
-    </div>
-  );
-}
-```
-
-### Multiple selection
-
-Use `ComboBoxStateContext` to render the selected items as a [TagGroup](TagGroup).
-
-```tsx render
-"use client";
-import {ComboBox, ComboBoxStateContext, Input} from 'react-aria-components';
+import {ComboBox, ComboBoxValue, Input} from 'react-aria-components';
 import {ComboBoxListBox, ComboBoxItem} from 'vanilla-starter/ComboBox';
 import {Label, FieldButton} from 'vanilla-starter/Form';
 import {Popover} from 'vanilla-starter/Popover';
@@ -218,12 +183,12 @@ const states = [
     <FieldButton><ChevronDown /></FieldButton>
   </div>
   {/*- begin highlight -*/}
-  <ComboBoxStateContext.Consumer>
-    {state => state && (
+  <ComboBoxValue>
+    {({selectedItems, state}) => (
       <TagGroup
         aria-label="Selected states"
         style={{marginTop: 8}}
-        items={state.selectedItems}
+        items={selectedItems}
         renderEmptyState={() => 'No selected items'}
         onRemove={(keys) => {
           // Remove keys from ComboBox state.
@@ -231,10 +196,10 @@ const states = [
             state.setValue(state.value.filter(k => !keys.has(k)));
           }
         }}>
-        {item => <Tag>{item.value.name}</Tag>}
+        {item => <Tag>{item.name}</Tag>}
       </TagGroup>
     )}
-  </ComboBoxStateContext.Consumer>
+  </ComboBoxValue>
   {/*- end highlight -*/}
   <Popover hideArrow className="combobox-popover">
     <ComboBoxListBox items={states}>
@@ -244,6 +209,41 @@ const states = [
 </ComboBox>
 ```
 
+## Value
+
+Use the `defaultValue` or `value` prop to set the selected item. The value corresponds to the `id` prop of an item. Items can be disabled with the `isDisabled` prop.
+
+```tsx render
+"use client";
+import {ComboBox, ComboBoxItem} from 'vanilla-starter/ComboBox';
+import {useState} from 'react';
+import type {Key} from 'react-aria-components';
+
+function Example() {
+  let [animal, setAnimal] = useState<Key | null>("bison");
+
+  return (
+    <div>
+      <ComboBox
+        label="Favorite Animal"
+        placeholder="Select an animal"
+        /*- begin highlight -*/
+        value={animal}
+        onChange={setAnimal}>
+        {/*- end highlight -*/}
+        <ComboBoxItem id="koala">Koala</ComboBoxItem>
+        <ComboBoxItem id="kangaroo">Kangaroo</ComboBoxItem>
+        <ComboBoxItem id="platypus" isDisabled>Platypus</ComboBoxItem>
+        <ComboBoxItem id="eagle">Bald Eagle</ComboBoxItem>
+        <ComboBoxItem id="bison">Bison</ComboBoxItem>
+        <ComboBoxItem id="skunk">Skunk</ComboBoxItem>
+      </ComboBox>
+      <p>Current selection: {animal}</p>
+    </div>
+  );
+}
+```
+
 ### Input value
 
 Use the `inputValue` or `defaultInputValue` prop to set the value of the input field. By default, the value will be reverted to the selected item on blur. Set the `allowsCustomValue` prop to enable entering values that are not in the list.
@@ -282,7 +282,7 @@ function Example(props) {
 
 ### Fully controlled
 
-Both `inputValue` and `selectedKey` can be controlled simultaneously. However, each interaction will only trigger either `onInputChange` or `onSelectionChange`, not both. When controlling both props, you must update both values accordingly.
+Both `inputValue` and `value` can be controlled simultaneously. However, each interaction will only trigger either `onInputChange` or `onChange`, not both. When controlling both props, you must update both values accordingly.
 
 ```tsx render
 "use client";
@@ -305,24 +305,24 @@ function ControlledComboBox() {
   ];
   /*- end collapse -*/
 
-  let [fieldState, setFieldState] = useState<{selectedKey: Key | null, inputValue: string}>({
-    selectedKey: null,
+  let [fieldState, setFieldState] = useState<{value: Key | null, inputValue: string}>({
+    value: null,
     inputValue: ''
   });
 
-  let onSelectionChange = (id: Key | null) => {
-    // Update inputValue when selectedKey changes.
+  let onChange = (id: Key | null) => {
+    // Update inputValue when value changes.
     setFieldState({
       inputValue: id == null ? '' : options.find(o => o.id === id)?.name ?? '',
-      selectedKey: id
+      value: id
     });
   };
 
   let onInputChange = (value: string) => {
-    // Reset selectedKey to null if the input is cleared.
+    // Reset value to null if the input is cleared.
     setFieldState(prevState => ({
       inputValue: value,
-      selectedKey: value === '' ? null : prevState.selectedKey
+      value: value === '' ? null : prevState.value
     }));
   };
 
@@ -333,15 +333,15 @@ function ControlledComboBox() {
         placeholder="Select a major"
         /*- begin highlight -*/
         defaultItems={options}
-        selectedKey={fieldState.selectedKey}
+        value={fieldState.value}
         inputValue={fieldState.inputValue}
-        onSelectionChange={onSelectionChange}
+        onChange={onChange}
         onInputChange={onInputChange}>
         {/*- end highlight -*/}
         {item => <ComboBoxItem>{item.name}</ComboBoxItem>}
       </ComboBox>
       <pre style={{fontSize: 12}}>
-        Current selected major id: {fieldState.selectedKey}{'\n'}
+        Current selected major id: {fieldState.value}{'\n'}
         Current input text: {fieldState.inputValue}
       </pre>
     </div>
@@ -444,11 +444,12 @@ import {ComboBox, ComboBoxItem} from 'vanilla-starter/ComboBox';
 
 <Anatomy />
 
-```tsx links={{ComboBox: '#combobox', Button: 'Button', Popover: 'Popover', ListBox: 'ListBox'}}
+```tsx links={{ComboBox: '#combobox', ComboBoxValue: '#comboboxvalue', Button: 'Button', Popover: 'Popover', ListBox: 'ListBox'}}
 <ComboBox>
   <Label />
   <Input />
   <Button />
+  <ComboBoxValue />
   <Text slot="description" />
   <FieldError />
   <Popover>
@@ -460,3 +461,7 @@ import {ComboBox, ComboBoxItem} from 'vanilla-starter/ComboBox';
 ### ComboBox
 
 <PropTable component={docs.exports.ComboBox} links={docs.links} />
+
+### ComboBoxValue
+
+<PropTable component={docs.exports.ComboBoxValue} links={docs.links} showDescription />
diff --git a/packages/dev/s2-docs/pages/react-aria/selection.mdx b/packages/dev/s2-docs/pages/react-aria/selection.mdx
index 98b46efb4e1..caf28adeb4f 100644
--- a/packages/dev/s2-docs/pages/react-aria/selection.mdx
+++ b/packages/dev/s2-docs/pages/react-aria/selection.mdx
@@ -481,12 +481,15 @@ function Example(props) {
 
 ## Single selection
 
-In some components like [ComboBox](ComboBox), only single selection is supported. In this case, the singular `selectedKey` and `defaultSelectedKey` props are available instead of their plural variants. These accept a single id instead of a `Set` as their value.
+In some components like [Tabs](Tabs), only single selection is supported. In this case, the singular `selectedKey` and `defaultSelectedKey` props are available instead of their plural variants. These accept a single id instead of a `Set` as their value.
 
 ```tsx render
 "use client";
 import type {Key} from 'react-aria-components';
-import {ComboBox, ComboBoxItem} from 'vanilla-starter/ComboBox';
+import {Tabs, TabList, Tab, TabPanels, TabPanel} from 'vanilla-starter/Tabs';
+import Home from '@react-spectrum/s2/illustrations/gradient/generic2/Home';
+import Folder from '@react-spectrum/s2/illustrations/gradient/generic2/FolderOpen';
+import Search from '@react-spectrum/s2/illustrations/gradient/generic2/Search';
 import {useState} from 'react';
 
 function Example() {
@@ -494,16 +497,28 @@ function Example() {
 
   return (
     <div>
-      <ComboBox
-        label="ComboBox"
+      <Tabs
         ///- begin highlight -///
         selectedKey={selectedKey}
         ///- end highlight -///
         onSelectionChange={setSelectedKey}>
-        <ComboBoxItem id="one">One</ComboBoxItem>
-        <ComboBoxItem id="two">Two</ComboBoxItem>
-        <ComboBoxItem id="three">Three</ComboBoxItem>
-      </ComboBox>
+        <TabList aria-label="Tabs">
+          <Tab id="home">Home</Tab>
+          <Tab id="files">Files</Tab>
+          <Tab id="search">Search</Tab>
+        </TabList>
+        <TabPanels>
+          <TabPanel id="home" style={{display: 'flex', alignItems: 'center', justifyContent: 'center'}}>
+            <Home />
+          </TabPanel>
+          <TabPanel id="files" style={{display: 'flex', alignItems: 'center', justifyContent: 'center'}}>
+            <Folder />
+          </TabPanel>
+          <TabPanel id="search" style={{display: 'flex', alignItems: 'center', justifyContent: 'center'}}>
+            <Search />
+          </TabPanel>
+        </TabPanels>
+      </Tabs>
       <p>selectedKey: {String(selectedKey)}</p>
     </div>
   );
diff --git a/packages/dev/s2-docs/src/PropTable.tsx b/packages/dev/s2-docs/src/PropTable.tsx
index 25789d9ec4a..4aeb843bdef 100644
--- a/packages/dev/s2-docs/src/PropTable.tsx
+++ b/packages/dev/s2-docs/src/PropTable.tsx
@@ -93,7 +93,7 @@ export function PropTable({component, links, showDescription, hideRenderProps, s
 
   return (
     <>
-      {component.description && showDescription && <div className={style({font: 'body'})}>{renderHTMLfromMarkdown(component.description, {forceInline: false, forceBlock: true})}</div>}
+      {component.description && showDescription && <div className={style({font: 'body', marginBottom: 16})}>{renderHTMLfromMarkdown(component.description, {forceInline: false, forceBlock: true})}</div>}
       <GroupedPropTable
         properties={properties}
         links={links}
diff --git a/packages/react-aria-components/src/ComboBox.tsx b/packages/react-aria-components/src/ComboBox.tsx
index e0414e1f378..2d1b2152503 100644
--- a/packages/react-aria-components/src/ComboBox.tsx
+++ b/packages/react-aria-components/src/ComboBox.tsx
@@ -9,7 +9,7 @@
  * OF ANY KIND, either express or implied. See the License for the specific language
  * governing permissions and limitations under the License.
  */
-import {AriaComboBoxProps, useComboBox, useFilter} from 'react-aria';
+import {AriaComboBoxProps, useComboBox, useFilter, useListFormatter} from 'react-aria';
 import {ButtonContext} from './Button';
 import {
   ClassNameOrFunction,
@@ -26,7 +26,7 @@ import {
   useSlottedContext
 } from './utils';
 import {Collection, ComboBoxState, Node, useComboBoxState} from 'react-stately';
-import {CollectionBuilder} from '@react-aria/collections';
+import {CollectionBuilder, createHideableComponent} from '@react-aria/collections';
 import {FieldErrorContext} from './FieldError';
 import {filterDOMProps, useResizeObserver} from '@react-aria/utils';
 import {FormContext} from './Form';
@@ -37,7 +37,7 @@ import {LabelContext} from './Label';
 import {ListBoxContext, ListStateContext} from './ListBox';
 import {OverlayTriggerStateContext} from './Dialog';
 import {PopoverContext} from './Popover';
-import React, {createContext, ForwardedRef, forwardRef, ReactElement, useCallback, useMemo, useRef, useState} from 'react';
+import React, {createContext, ForwardedRef, forwardRef, HTMLAttributes, ReactElement, ReactNode, useCallback, useContext, useMemo, useRef, useState} from 'react';
 import {TextContext} from './Text';
 
 type SelectionMode = 'single' | 'multiple';
@@ -260,3 +260,59 @@ function ComboBoxInner<T extends object>({props, collection, comboBoxRef: ref}:
     </Provider>
   );
 }
+
+export interface ComboBoxValueRenderProps<T> {
+  /**
+   * Whether the value is a placeholder.
+   * @selector [data-placeholder]
+   */
+  isPlaceholder: boolean,
+  /** The object values of the currently selected items. */
+  selectedItems: (T | null)[],
+  /** The textValue of the currently selected items. */
+  selectedText: string,
+  /** The state of the ComboBox. */
+  state: ComboBoxState<T, 'single' | 'multiple'>
+}
+
+export interface ComboBoxValueProps<T extends object> extends Omit<HTMLAttributes<HTMLElement>, keyof RenderProps<unknown>>, RenderProps<ComboBoxValueRenderProps<T>, 'div'> {
+  /**
+   * The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state.
+   * @default 'react-aria-ComboBoxValue'
+   */
+  className?: ClassNameOrFunction<ComboBoxValueRenderProps<T>>,
+  /** A value to display when no items are selected. */
+  placeholder?: ReactNode
+}
+
+/**
+ * ComboBoxValue renders the selected values of a ComboBox, or a placeholder if no value is selected.
+ * By default, the items are rendered as a comma separated list. Use the render function to customize this.
+ */
+export const ComboBoxValue = /*#__PURE__*/ createHideableComponent(function ComboBoxValue<T extends object>(props: ComboBoxValueProps<T>, ref: ForwardedRef<HTMLDivElement>) {
+  let state = useContext(ComboBoxStateContext)!;
+  let formatter = useListFormatter();
+  let selectedText = useMemo(() => formatter.format(state.selectedItems.map(item => item?.textValue || '').filter(v => v !== '')), [formatter, state.selectedItems]);
+
+  let renderProps = useRenderProps({
+    ...props,
+    defaultChildren: selectedText || props.placeholder,
+    defaultClassName: 'react-aria-ComboBoxValue',
+    values: {
+      selectedItems: useMemo(() => state.selectedItems.map(item => item.value as T ?? null), [state.selectedItems]),
+      selectedText,
+      isPlaceholder: state.selectedItems.length === 0,
+      state
+    }
+  });
+
+  let DOMProps = filterDOMProps(props, {global: true});
+
+  return (
+    <dom.div
+      ref={ref}
+      {...DOMProps}
+      {...renderProps}
+      data-placeholder={state.selectedItems.length === 0 || undefined} />
+  );
+});
diff --git a/packages/react-aria-components/src/index.ts b/packages/react-aria-components/src/index.ts
index fe3d37dfe97..8971db53e82 100644
--- a/packages/react-aria-components/src/index.ts
+++ b/packages/react-aria-components/src/index.ts
@@ -29,7 +29,7 @@ export {ColorSwatch, ColorSwatchContext} from './ColorSwatch';
 export {ColorSwatchPicker, ColorSwatchPickerItem, ColorSwatchPickerContext} from './ColorSwatchPicker';
 export {ColorThumb} from './ColorThumb';
 export {ColorWheel, ColorWheelTrack, ColorWheelTrackContext, ColorWheelStateContext} from './ColorWheel';
-export {ComboBox, ComboBoxContext, ComboBoxStateContext} from './ComboBox';
+export {ComboBox, ComboBoxValue, ComboBoxContext, ComboBoxStateContext} from './ComboBox';
 export {composeRenderProps, DEFAULT_SLOT, Provider, useContextProps, useRenderProps, useSlottedContext} from './utils';
 export {DateField, DateInput, DateSegment, TimeField, DateFieldContext, TimeFieldContext, DateFieldStateContext, TimeFieldStateContext} from './DateField';
 export {DatePicker, DateRangePicker, DatePickerContext, DateRangePickerContext, DatePickerStateContext, DateRangePickerStateContext} from './DatePicker';
@@ -100,7 +100,7 @@ export type {ColorSwatchPickerProps, ColorSwatchPickerRenderProps, ColorSwatchPi
 export type {ColorThumbProps, ColorThumbRenderProps} from './ColorThumb';
 export type {ColorPickerProps, ColorPickerRenderProps} from './ColorPicker';
 export type {ColorWheelProps, ColorWheelRenderProps, ColorWheelTrackProps, ColorWheelTrackRenderProps} from './ColorWheel';
-export type {ComboBoxProps, ComboBoxRenderProps} from './ComboBox';
+export type {ComboBoxProps, ComboBoxRenderProps, ComboBoxValueProps, ComboBoxValueRenderProps} from './ComboBox';
 export type {DateFieldProps, DateFieldRenderProps, DateInputProps, DateInputRenderProps, DateSegmentProps, DateSegmentRenderProps, TimeFieldProps} from './DateField';
 export type {DatePickerProps, DatePickerRenderProps, DateRangePickerProps, DateRangePickerRenderProps} from './DatePicker';
 export type {DialogProps, DialogTriggerProps, DialogRenderProps} from './Dialog';
diff --git a/starters/docs/src/ComboBox.css b/starters/docs/src/ComboBox.css
index 2c6eaeb2246..d2ee26afbb1 100644
--- a/starters/docs/src/ComboBox.css
+++ b/starters/docs/src/ComboBox.css
@@ -16,6 +16,11 @@
     width: 100%;
     padding: 0 calc(var(--spacing-3) + var(--spacing-6)) 0 var(--spacing-3);
   }
+
+  .react-aria-ComboBoxValue {
+    margin-top: var(--spacing-1);
+    font: var(--font-size-sm) system-ui;
+  }
 }
 
 .combobox-popover[data-trigger=ComboBox] {
diff --git a/starters/docs/src/ComboBox.tsx b/starters/docs/src/ComboBox.tsx
index e2e6d458790..9c35ec1134d 100644
--- a/starters/docs/src/ComboBox.tsx
+++ b/starters/docs/src/ComboBox.tsx
@@ -2,6 +2,7 @@
 import {
   ComboBox as AriaComboBox,
   ComboBoxProps as AriaComboBoxProps,
+  ComboBoxValue,
   Input,
   ListBoxItemProps,
   ListBoxProps,
@@ -14,8 +15,8 @@ import {ChevronDown} from 'lucide-react';
 
 import './ComboBox.css';
 
-export interface ComboBoxProps<T extends object>
-  extends Omit<AriaComboBoxProps<T>, 'children'> {
+export interface ComboBoxProps<T extends object, M extends 'single' | 'multiple'>
+  extends Omit<AriaComboBoxProps<T, M>, 'children'> {
   label?: string;
   description?: string | null;
   errorMessage?: string | ((validation: ValidationResult) => string);
@@ -23,8 +24,8 @@ export interface ComboBoxProps<T extends object>
   placeholder?: string;
 }
 
-export function ComboBox<T extends object>(
-  { label, description, errorMessage, children, placeholder, ...props }: ComboBoxProps<T>
+export function ComboBox<T extends object, M extends 'single' | 'multiple'>(
+  { label, description, errorMessage, children, placeholder, ...props }: ComboBoxProps<T, M>
 ) {
   return (
     <AriaComboBox {...props}>
@@ -33,6 +34,7 @@ export function ComboBox<T extends object>(
         <Input className="react-aria-Input inset" placeholder={placeholder} />
         <FieldButton><ChevronDown /></FieldButton>
       </div>
+      {props.selectionMode === 'multiple' && <ComboBoxValue placeholder="No items selected" />}
       {description && <Description>{description}</Description>}
       <FieldError>{errorMessage}</FieldError>
       <Popover hideArrow className="combobox-popover">
diff --git a/starters/docs/src/Select.tsx b/starters/docs/src/Select.tsx
index 9d8bae7b804..f2f1f45a610 100644
--- a/starters/docs/src/Select.tsx
+++ b/starters/docs/src/Select.tsx
@@ -14,8 +14,7 @@ import {Popover} from './Popover';
 import {Label, FieldError, Description} from './Form';
 import './Select.css';
 
-export interface SelectProps<T extends object>
-  extends Omit<AriaSelectProps<T>, 'children'> {
+export interface SelectProps<T extends object, M extends 'single' | 'multiple'> extends Omit<AriaSelectProps<T, M>, 'children'> {
   label?: string;
   description?: string;
   errorMessage?: string | ((validation: ValidationResult) => string);
@@ -23,10 +22,8 @@ export interface SelectProps<T extends object>
   children: React.ReactNode | ((item: T) => React.ReactNode);
 }
 
-export function Select<T extends object>(
-  { label, description, errorMessage, children, items, ...props }: SelectProps<
-    T
-  >
+export function Select<T extends object, M extends 'single' | 'multiple'>(
+  { label, description, errorMessage, children, items, ...props }: SelectProps<T, M>
 ) {
   return (
     (
diff --git a/starters/tailwind/src/ComboBox.tsx b/starters/tailwind/src/ComboBox.tsx
index 468b5e0d7fa..1268eac1bde 100644
--- a/starters/tailwind/src/ComboBox.tsx
+++ b/starters/tailwind/src/ComboBox.tsx
@@ -4,6 +4,7 @@ import React from 'react';
 import {
   ComboBox as AriaComboBox,
   ComboBoxProps as AriaComboBoxProps,
+  ComboBoxValue,
   ListBox,
   ListBoxItemProps,
   ValidationResult
@@ -14,7 +15,7 @@ import { Popover } from './Popover';
 import { composeTailwindRenderProps } from './utils';
 import { FieldButton } from './FieldButton';
 
-export interface ComboBoxProps<T extends object> extends Omit<AriaComboBoxProps<T>, 'children'> {
+export interface ComboBoxProps<T extends object, M extends 'single' | 'multiple'> extends Omit<AriaComboBoxProps<T, M>, 'children'> {
   label?: string;
   description?: string | null;
   errorMessage?: string | ((validation: ValidationResult) => string);
@@ -22,8 +23,8 @@ export interface ComboBoxProps<T extends object> extends Omit<AriaComboBoxProps<
   children: React.ReactNode | ((item: T) => React.ReactNode);
 }
 
-export function ComboBox<T extends object>(
-  { label, description, errorMessage, children, items, ...props }: ComboBoxProps<T>
+export function ComboBox<T extends object, M extends 'single' | 'multiple'>(
+  { label, description, errorMessage, children, items, ...props }: ComboBoxProps<T, M>
 ) {
   return (
     <AriaComboBox {...props} className={composeTailwindRenderProps(props.className, 'group flex flex-col gap-1 font-sans')}>
@@ -34,6 +35,7 @@ export function ComboBox<T extends object>(
           <ChevronDown aria-hidden className="w-4 h-4" />
         </FieldButton>
       </FieldGroup>
+      {props.selectionMode === 'multiple' && <ComboBoxValue placeholder="No items selected" className="text-xs text-neutral-600" />}
       {description && <Description>{description}</Description>}
       <FieldError>{errorMessage}</FieldError>
       <Popover className="w-(--trigger-width)">
diff --git a/starters/tailwind/src/Select.tsx b/starters/tailwind/src/Select.tsx
index 94e6b9efb32..650bd404576 100644
--- a/starters/tailwind/src/Select.tsx
+++ b/starters/tailwind/src/Select.tsx
@@ -27,7 +27,7 @@ const styles = tv({
   }
 });
 
-export interface SelectProps<T extends object> extends Omit<AriaSelectProps<T>, 'children'> {
+export interface SelectProps<T extends object, M extends 'single' | 'multiple'> extends Omit<AriaSelectProps<T, M>, 'children'> {
   label?: string;
   description?: string;
   errorMessage?: string | ((validation: ValidationResult) => string);
@@ -35,8 +35,8 @@ export interface SelectProps<T extends object> extends Omit<AriaSelectProps<T>,
   children: React.ReactNode | ((item: T) => React.ReactNode);
 }
 
-export function Select<T extends object>(
-  { label, description, errorMessage, children, items, ...props }: SelectProps<T>
+export function Select<T extends object, M extends 'single' | 'multiple'>(
+  { label, description, errorMessage, children, items, ...props }: SelectProps<T, M>
 ) {
   return (
     <AriaSelect {...props} className={composeTailwindRenderProps(props.className, 'group flex flex-col gap-1 relative font-sans')}>

From 4f16c611d3879e5eb278e40bd1fb183c23aa869d Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Thu, 5 Feb 2026 17:09:51 -0800
Subject: [PATCH 09/11] Associate ComboBoxValue via aria-describedby

---
 packages/@react-aria/combobox/src/useComboBox.ts      | 11 +++++++++--
 .../@react-spectrum/combobox/test/ComboBox.test.js    |  4 ++--
 packages/react-aria-components/src/ComboBox.tsx       |  7 ++++++-
 packages/react-aria-components/src/index.ts           |  2 +-
 packages/react-aria-components/test/ComboBox.test.js  |  9 ++++++++-
 5 files changed, 26 insertions(+), 7 deletions(-)

diff --git a/packages/@react-aria/combobox/src/useComboBox.ts b/packages/@react-aria/combobox/src/useComboBox.ts
index 0dbb685e2b4..f6c294b7858 100644
--- a/packages/@react-aria/combobox/src/useComboBox.ts
+++ b/packages/@react-aria/combobox/src/useComboBox.ts
@@ -16,7 +16,7 @@ import {AriaComboBoxProps, SelectionMode} from '@react-types/combobox';
 import {ariaHideOutside} from '@react-aria/overlays';
 import {AriaListBoxOptions, getItemId, listData} from '@react-aria/listbox';
 import {BaseEvent, DOMAttributes, KeyboardDelegate, LayoutDelegate, PressEvent, RefObject, RouterOptions, ValidationResult} from '@react-types/shared';
-import {chain, getActiveElement, getOwnerDocument, isAppleDevice, mergeProps, nodeContains, useEvent, useFormReset, useLabels, useRouter, useUpdateEffect} from '@react-aria/utils';
+import {chain, getActiveElement, getOwnerDocument, isAppleDevice, mergeProps, nodeContains, useEvent, useFormReset, useLabels, useRouter, useSlotId, useUpdateEffect} from '@react-aria/utils';
 import {ComboBoxState} from '@react-stately/combobox';
 import {dispatchVirtualFocus} from '@react-aria/focus';
 import {FocusEvent, InputHTMLAttributes, KeyboardEvent, TouchEvent, useEffect, useMemo, useRef} from 'react';
@@ -57,6 +57,8 @@ export interface ComboBoxAria<T> extends ValidationResult {
   listBoxProps: AriaListBoxOptions<T>,
   /** Props for the optional trigger button, to be passed to `useButton`. */
   buttonProps: AriaButtonProps,
+  /** Props for the element representing the selected value. */
+  valueProps: DOMAttributes,
   /** Props for the combo box description element, if any. */
   descriptionProps: DOMAttributes,
   /** Props for the combo box error message element, if any. */
@@ -206,6 +208,7 @@ export function useComboBox<T, M extends SelectionMode = 'single'>(props: AriaCo
     state.setFocused(true);
   };
 
+  let valueId = useSlotId([state.selectedItems, state.selectionManager.selectionMode]);
   let {isInvalid, validationErrors, validationDetails} = state.displayValidation;
   let {labelProps, inputProps, descriptionProps, errorMessageProps} = useTextField({
     ...props,
@@ -217,7 +220,8 @@ export function useComboBox<T, M extends SelectionMode = 'single'>(props: AriaCo
     onFocus,
     autoComplete: 'off',
     validate: undefined,
-    [privateValidationStateProp]: state
+    [privateValidationStateProp]: state,
+    'aria-describedby': [valueId, props['aria-describedby']].filter(Boolean).join(' ') || undefined
   }, inputRef);
 
   useFormReset(inputRef, state.defaultValue, state.setValue);
@@ -393,6 +397,9 @@ export function useComboBox<T, M extends SelectionMode = 'single'>(props: AriaCo
       linkBehavior: 'selection' as const,
       ['UNSTABLE_itemBehavior']: 'action'
     }),
+    valueProps: {
+      id: valueId
+    },
     descriptionProps,
     errorMessageProps,
     isInvalid,
diff --git a/packages/@react-spectrum/combobox/test/ComboBox.test.js b/packages/@react-spectrum/combobox/test/ComboBox.test.js
index 167e59e665f..d2177dd51af 100644
--- a/packages/@react-spectrum/combobox/test/ComboBox.test.js
+++ b/packages/@react-spectrum/combobox/test/ComboBox.test.js
@@ -5286,11 +5286,11 @@ describe('ComboBox', function () {
           expect(input).toHaveValue('One');
     
           let button = getByTestId('submit');
-          await act(async () => await user.click(button));
+          await user.click(button);
           expect(input).toHaveValue('Two');
 
           rerender(<Test formValue="key" />);
-          await act(async () => await user.click(button));
+          await user.click(button);
           expect(document.querySelector('input[name=combobox]')).toHaveValue('2');
         });
       }
diff --git a/packages/react-aria-components/src/ComboBox.tsx b/packages/react-aria-components/src/ComboBox.tsx
index 2d1b2152503..f773bf926ea 100644
--- a/packages/react-aria-components/src/ComboBox.tsx
+++ b/packages/react-aria-components/src/ComboBox.tsx
@@ -159,6 +159,7 @@ function ComboBoxInner<T extends object>({props, collection, comboBoxRef: ref}:
     labelProps,
     descriptionProps,
     errorMessageProps,
+    valueProps,
     ...validation
   } = useComboBox({
     ...removeDataAttributes(props),
@@ -244,7 +245,8 @@ function ComboBoxInner<T extends object>({props, collection, comboBoxRef: ref}:
           }
         }],
         [GroupContext, {isInvalid: validation.isInvalid, isDisabled: props.isDisabled || false}],
-        [FieldErrorContext, validation]
+        [FieldErrorContext, validation],
+        [ComboBoxValueContext, valueProps]
       ]}>
       <dom.div
         {...DOMProps}
@@ -285,11 +287,14 @@ export interface ComboBoxValueProps<T extends object> extends Omit<HTMLAttribute
   placeholder?: ReactNode
 }
 
+export const ComboBoxValueContext = createContext<ContextValue<ComboBoxValueProps<any>, HTMLDivElement>>(null);
+
 /**
  * ComboBoxValue renders the selected values of a ComboBox, or a placeholder if no value is selected.
  * By default, the items are rendered as a comma separated list. Use the render function to customize this.
  */
 export const ComboBoxValue = /*#__PURE__*/ createHideableComponent(function ComboBoxValue<T extends object>(props: ComboBoxValueProps<T>, ref: ForwardedRef<HTMLDivElement>) {
+  [props, ref] = useContextProps(props, ref, ComboBoxValueContext);
   let state = useContext(ComboBoxStateContext)!;
   let formatter = useListFormatter();
   let selectedText = useMemo(() => formatter.format(state.selectedItems.map(item => item?.textValue || '').filter(v => v !== '')), [formatter, state.selectedItems]);
diff --git a/packages/react-aria-components/src/index.ts b/packages/react-aria-components/src/index.ts
index 8971db53e82..6eaedbff5a9 100644
--- a/packages/react-aria-components/src/index.ts
+++ b/packages/react-aria-components/src/index.ts
@@ -29,7 +29,7 @@ export {ColorSwatch, ColorSwatchContext} from './ColorSwatch';
 export {ColorSwatchPicker, ColorSwatchPickerItem, ColorSwatchPickerContext} from './ColorSwatchPicker';
 export {ColorThumb} from './ColorThumb';
 export {ColorWheel, ColorWheelTrack, ColorWheelTrackContext, ColorWheelStateContext} from './ColorWheel';
-export {ComboBox, ComboBoxValue, ComboBoxContext, ComboBoxStateContext} from './ComboBox';
+export {ComboBox, ComboBoxValue, ComboBoxContext, ComboBoxStateContext, ComboBoxValueContext} from './ComboBox';
 export {composeRenderProps, DEFAULT_SLOT, Provider, useContextProps, useRenderProps, useSlottedContext} from './utils';
 export {DateField, DateInput, DateSegment, TimeField, DateFieldContext, TimeFieldContext, DateFieldStateContext, TimeFieldStateContext} from './DateField';
 export {DatePicker, DateRangePicker, DatePickerContext, DateRangePickerContext, DatePickerStateContext, DateRangePickerStateContext} from './DatePicker';
diff --git a/packages/react-aria-components/test/ComboBox.test.js b/packages/react-aria-components/test/ComboBox.test.js
index 68c09257d6e..9aee03b0cdd 100644
--- a/packages/react-aria-components/test/ComboBox.test.js
+++ b/packages/react-aria-components/test/ComboBox.test.js
@@ -11,7 +11,7 @@
  */
 
 import {act} from '@testing-library/react';
-import {Button, ComboBox, ComboBoxContext, FieldError, Form, Header, Input, Label, ListBox, ListBoxItem, ListBoxLoadMoreItem, ListBoxSection, ListLayout, Popover, Text, Virtualizer} from '../';
+import {Button, ComboBox, ComboBoxContext, ComboBoxValue, FieldError, Form, Header, Input, Label, ListBox, ListBoxItem, ListBoxLoadMoreItem, ListBoxSection, ListLayout, Popover, Text, Virtualizer} from '../';
 import {fireEvent, pointerMap, render, within} from '@react-spectrum/test-utils-internal';
 import React, {useState} from 'react';
 import {User} from '@react-aria/test-utils';
@@ -28,6 +28,7 @@ let TestComboBox = (props) => (
     <Label>Favorite Animal</Label>
     <Input />
     <Button />
+    {props.selectionMode === 'multiple' && <ComboBoxValue placeholder="No items selected" />}
     <Text slot="description">Description</Text>
     <Text slot="errorMessage">Error</Text>
     <Popover>
@@ -637,6 +638,10 @@ describe('ComboBox', () => {
       </Form>
     );
     let comboboxTester = testUtilUser.createTester('ComboBox', {root: container});
+    let value = container.querySelector('.react-aria-ComboBoxValue');
+
+    expect(value).toHaveTextContent('No items selected');
+    expect(comboboxTester.combobox.getAttribute('aria-describedby')).toContain(value.id);
 
     expect(comboboxTester.combobox).toHaveValue('');
     await comboboxTester.open();
@@ -651,10 +656,12 @@ describe('ComboBox', () => {
     expect(options[0]).toHaveAttribute('aria-selected', 'true');
     expect(comboboxTester.combobox).toHaveValue('');
     expect(comboboxTester.listbox).toBeInTheDocument();
+    expect(value).toHaveTextContent('Cat');
     await user.click(options[1]);
     expect(options[1]).toHaveAttribute('aria-selected', 'true');
     expect(comboboxTester.combobox).toHaveValue('');
     expect(comboboxTester.listbox).toBeInTheDocument();
+    expect(value).toHaveTextContent('Cat and Dog');
     await comboboxTester.close();
 
     expect(onChange).toHaveBeenCalledTimes(2);

From 86ef3b458cc5d97546b9fb2edccab435bfa7a454 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Thu, 5 Feb 2026 17:22:13 -0800
Subject: [PATCH 10/11] fix TS and test

---
 .../autocomplete/test/SearchAutocomplete.test.js      |  2 +-
 packages/dev/s2-docs/pages/react-aria/ComboBox.mdx    |  4 ++--
 packages/react-aria-components/src/utils.tsx          | 11 ++++++-----
 starters/docs/src/ComboBox.tsx                        |  2 +-
 starters/docs/src/Select.tsx                          |  2 +-
 starters/tailwind/src/ComboBox.tsx                    |  2 +-
 starters/tailwind/src/Select.tsx                      |  2 +-
 7 files changed, 13 insertions(+), 12 deletions(-)

diff --git a/packages/@react-spectrum/autocomplete/test/SearchAutocomplete.test.js b/packages/@react-spectrum/autocomplete/test/SearchAutocomplete.test.js
index 0ef2af2f80e..d663cb84623 100644
--- a/packages/@react-spectrum/autocomplete/test/SearchAutocomplete.test.js
+++ b/packages/@react-spectrum/autocomplete/test/SearchAutocomplete.test.js
@@ -2479,7 +2479,7 @@ describe('SearchAutocomplete', function () {
           expect(input).toHaveValue('test');
     
           let button = getByTestId('submit');
-          await act(async () => await user.click(button));
+          await user.click(button);
           expect(input).toHaveValue('hi');
         });
       }
diff --git a/packages/dev/s2-docs/pages/react-aria/ComboBox.mdx b/packages/dev/s2-docs/pages/react-aria/ComboBox.mdx
index b106693150e..cc102cadfcb 100644
--- a/packages/dev/s2-docs/pages/react-aria/ComboBox.mdx
+++ b/packages/dev/s2-docs/pages/react-aria/ComboBox.mdx
@@ -183,12 +183,12 @@ const states = [
     <FieldButton><ChevronDown /></FieldButton>
   </div>
   {/*- begin highlight -*/}
-  <ComboBoxValue>
+  <ComboBoxValue<typeof states[0]>>
     {({selectedItems, state}) => (
       <TagGroup
         aria-label="Selected states"
         style={{marginTop: 8}}
-        items={selectedItems}
+        items={selectedItems.filter(item => item != null)}
         renderEmptyState={() => 'No selected items'}
         onRemove={(keys) => {
           // Remove keys from ComboBox state.
diff --git a/packages/react-aria-components/src/utils.tsx b/packages/react-aria-components/src/utils.tsx
index 501379df2de..414737439c6 100644
--- a/packages/react-aria-components/src/utils.tsx
+++ b/packages/react-aria-components/src/utils.tsx
@@ -24,7 +24,7 @@ export type SlottedContextValue<T> = (SlottedValue<T> & T) | null | undefined;
 export type ContextValue<T, E> = SlottedContextValue<WithRef<T, E>>;
 
 type ProviderValue<T> = [Context<T>, T];
-type ProviderValues<A, B, C, D, E, F, G, H, I, J, K> =
+type ProviderValues<A, B, C, D, E, F, G, H, I, J, K, L> =
   | [ProviderValue<A>]
   | [ProviderValue<A>, ProviderValue<B>]
   | [ProviderValue<A>, ProviderValue<B>, ProviderValue<C>]
@@ -35,14 +35,15 @@ type ProviderValues<A, B, C, D, E, F, G, H, I, J, K> =
   | [ProviderValue<A>, ProviderValue<B>, ProviderValue<C>, ProviderValue<D>, ProviderValue<E>, ProviderValue<F>, ProviderValue<G>, ProviderValue<H>]
   | [ProviderValue<A>, ProviderValue<B>, ProviderValue<C>, ProviderValue<D>, ProviderValue<E>, ProviderValue<F>, ProviderValue<G>, ProviderValue<H>, ProviderValue<I>]
   | [ProviderValue<A>, ProviderValue<B>, ProviderValue<C>, ProviderValue<D>, ProviderValue<E>, ProviderValue<F>, ProviderValue<G>, ProviderValue<H>, ProviderValue<I>, ProviderValue<J>]
-  | [ProviderValue<A>, ProviderValue<B>, ProviderValue<C>, ProviderValue<D>, ProviderValue<E>, ProviderValue<F>, ProviderValue<G>, ProviderValue<H>, ProviderValue<I>, ProviderValue<J>, ProviderValue<K>];
+  | [ProviderValue<A>, ProviderValue<B>, ProviderValue<C>, ProviderValue<D>, ProviderValue<E>, ProviderValue<F>, ProviderValue<G>, ProviderValue<H>, ProviderValue<I>, ProviderValue<J>, ProviderValue<K>]
+  | [ProviderValue<A>, ProviderValue<B>, ProviderValue<C>, ProviderValue<D>, ProviderValue<E>, ProviderValue<F>, ProviderValue<G>, ProviderValue<H>, ProviderValue<I>, ProviderValue<J>, ProviderValue<K>, ProviderValue<L>];
 
-interface ProviderProps<A, B, C, D, E, F, G, H, I, J, K> {
-  values: ProviderValues<A, B, C, D, E, F, G, H, I, J, K>,
+interface ProviderProps<A, B, C, D, E, F, G, H, I, J, K, L> {
+  values: ProviderValues<A, B, C, D, E, F, G, H, I, J, K, L>,
   children: ReactNode
 }
 
-export function Provider<A, B, C, D, E, F, G, H, I, J, K>({values, children}: ProviderProps<A, B, C, D, E, F, G, H, I, J, K>): JSX.Element {
+export function Provider<A, B, C, D, E, F, G, H, I, J, K, L>({values, children}: ProviderProps<A, B, C, D, E, F, G, H, I, J, K, L>): JSX.Element {
   for (let [Context, value] of values) {
     // @ts-ignore
     children = <Context.Provider value={value}>{children}</Context.Provider>;
diff --git a/starters/docs/src/ComboBox.tsx b/starters/docs/src/ComboBox.tsx
index 9c35ec1134d..df074e27731 100644
--- a/starters/docs/src/ComboBox.tsx
+++ b/starters/docs/src/ComboBox.tsx
@@ -24,7 +24,7 @@ export interface ComboBoxProps<T extends object, M extends 'single' | 'multiple'
   placeholder?: string;
 }
 
-export function ComboBox<T extends object, M extends 'single' | 'multiple'>(
+export function ComboBox<T extends object, M extends 'single' | 'multiple' = 'single'>(
   { label, description, errorMessage, children, placeholder, ...props }: ComboBoxProps<T, M>
 ) {
   return (
diff --git a/starters/docs/src/Select.tsx b/starters/docs/src/Select.tsx
index f2f1f45a610..8e29ba0a536 100644
--- a/starters/docs/src/Select.tsx
+++ b/starters/docs/src/Select.tsx
@@ -22,7 +22,7 @@ export interface SelectProps<T extends object, M extends 'single' | 'multiple'>
   children: React.ReactNode | ((item: T) => React.ReactNode);
 }
 
-export function Select<T extends object, M extends 'single' | 'multiple'>(
+export function Select<T extends object, M extends 'single' | 'multiple' = 'single'>(
   { label, description, errorMessage, children, items, ...props }: SelectProps<T, M>
 ) {
   return (
diff --git a/starters/tailwind/src/ComboBox.tsx b/starters/tailwind/src/ComboBox.tsx
index 1268eac1bde..27e2e0c7423 100644
--- a/starters/tailwind/src/ComboBox.tsx
+++ b/starters/tailwind/src/ComboBox.tsx
@@ -23,7 +23,7 @@ export interface ComboBoxProps<T extends object, M extends 'single' | 'multiple'
   children: React.ReactNode | ((item: T) => React.ReactNode);
 }
 
-export function ComboBox<T extends object, M extends 'single' | 'multiple'>(
+export function ComboBox<T extends object, M extends 'single' | 'multiple' = 'single'>(
   { label, description, errorMessage, children, items, ...props }: ComboBoxProps<T, M>
 ) {
   return (
diff --git a/starters/tailwind/src/Select.tsx b/starters/tailwind/src/Select.tsx
index 650bd404576..63f744ed011 100644
--- a/starters/tailwind/src/Select.tsx
+++ b/starters/tailwind/src/Select.tsx
@@ -35,7 +35,7 @@ export interface SelectProps<T extends object, M extends 'single' | 'multiple'>
   children: React.ReactNode | ((item: T) => React.ReactNode);
 }
 
-export function Select<T extends object, M extends 'single' | 'multiple'>(
+export function Select<T extends object, M extends 'single' | 'multiple' = 'single'>(
   { label, description, errorMessage, children, items, ...props }: SelectProps<T, M>
 ) {
   return (

From 18b17026aa10b6f5ae030d6a44454c84123d3cf4 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Fri, 6 Feb 2026 10:24:44 -0800
Subject: [PATCH 11/11] work around issue in React 18 tests

---
 .../@react-aria/combobox/src/useComboBox.ts   | 32 +++++++++++++++++--
 .../test/SearchAutocomplete.test.js           |  3 +-
 .../combobox/test/ComboBox.test.js            |  3 +-
 3 files changed, 33 insertions(+), 5 deletions(-)

diff --git a/packages/@react-aria/combobox/src/useComboBox.ts b/packages/@react-aria/combobox/src/useComboBox.ts
index f6c294b7858..2bac2e28722 100644
--- a/packages/@react-aria/combobox/src/useComboBox.ts
+++ b/packages/@react-aria/combobox/src/useComboBox.ts
@@ -16,10 +16,10 @@ import {AriaComboBoxProps, SelectionMode} from '@react-types/combobox';
 import {ariaHideOutside} from '@react-aria/overlays';
 import {AriaListBoxOptions, getItemId, listData} from '@react-aria/listbox';
 import {BaseEvent, DOMAttributes, KeyboardDelegate, LayoutDelegate, PressEvent, RefObject, RouterOptions, ValidationResult} from '@react-types/shared';
-import {chain, getActiveElement, getOwnerDocument, isAppleDevice, mergeProps, nodeContains, useEvent, useFormReset, useLabels, useRouter, useSlotId, useUpdateEffect} from '@react-aria/utils';
+import {chain, getActiveElement, getOwnerDocument, isAppleDevice, mergeProps, nodeContains, useEvent, useFormReset, useId, useLabels, useRouter, useUpdateEffect} from '@react-aria/utils';
 import {ComboBoxState} from '@react-stately/combobox';
 import {dispatchVirtualFocus} from '@react-aria/focus';
-import {FocusEvent, InputHTMLAttributes, KeyboardEvent, TouchEvent, useEffect, useMemo, useRef} from 'react';
+import {FocusEvent, InputHTMLAttributes, KeyboardEvent, TouchEvent, useEffect, useMemo, useRef, useState} from 'react';
 import {getChildNodes, getItemCount} from '@react-stately/collections';
 // @ts-ignore
 import intlMessages from '../intl/*.json';
@@ -208,7 +208,7 @@ export function useComboBox<T, M extends SelectionMode = 'single'>(props: AriaCo
     state.setFocused(true);
   };
 
-  let valueId = useSlotId([state.selectedItems, state.selectionManager.selectionMode]);
+  let valueId = useValueId([state.selectedItems, state.selectionManager.selectionMode]);
   let {isInvalid, validationErrors, validationDetails} = state.displayValidation;
   let {labelProps, inputProps, descriptionProps, errorMessageProps} = useTextField({
     ...props,
@@ -407,3 +407,29 @@ export function useComboBox<T, M extends SelectionMode = 'single'>(props: AriaCo
     validationDetails
   };
 }
+
+// This is a modified version of useSlotId that uses useEffect instead of useLayoutEffect.
+// Triggering re-renders from useLayoutEffect breaks useComboBoxState's useEffect logic in React 18.
+// These re-renders preempt async state updates in the useEffect, which ends up running multiple times
+// prior to the state being updated. This results in onSelectionChange being called multiple times.
+// TODO: refactor useComboBoxState to avoid this.
+function useValueId(depArray: ReadonlyArray<any> = []): string | undefined {
+  let id = useId();
+  let [exists, setExists] = useState(true);
+  let [lastDeps, setLastDeps] = useState(depArray);
+
+  // If the deps changed, set exists to true so we can test whether the element exists.
+  if (lastDeps.some((v, i) => !Object.is(v, depArray[i]))) {
+    setExists(true);
+    setLastDeps(depArray);
+  }
+
+  useEffect(() => {
+    if (exists && !document.getElementById(id)) {
+      // eslint-disable-next-line react-hooks/set-state-in-effect
+      setExists(false);
+    }
+  }, [id, exists, lastDeps]);
+
+  return exists ? id : undefined;
+}
diff --git a/packages/@react-spectrum/autocomplete/test/SearchAutocomplete.test.js b/packages/@react-spectrum/autocomplete/test/SearchAutocomplete.test.js
index d663cb84623..eb02f61880d 100644
--- a/packages/@react-spectrum/autocomplete/test/SearchAutocomplete.test.js
+++ b/packages/@react-spectrum/autocomplete/test/SearchAutocomplete.test.js
@@ -2479,7 +2479,8 @@ describe('SearchAutocomplete', function () {
           expect(input).toHaveValue('test');
     
           let button = getByTestId('submit');
-          await user.click(button);
+          // For some reason, user.click() causes act warnings related to suspense...
+          await act(() => button.click());
           expect(input).toHaveValue('hi');
         });
       }
diff --git a/packages/@react-spectrum/combobox/test/ComboBox.test.js b/packages/@react-spectrum/combobox/test/ComboBox.test.js
index d2177dd51af..245127dd922 100644
--- a/packages/@react-spectrum/combobox/test/ComboBox.test.js
+++ b/packages/@react-spectrum/combobox/test/ComboBox.test.js
@@ -5286,7 +5286,8 @@ describe('ComboBox', function () {
           expect(input).toHaveValue('One');
     
           let button = getByTestId('submit');
-          await user.click(button);
+          // For some reason, user.click() causes act warnings related to suspense...
+          await act(() => button.click());
           expect(input).toHaveValue('Two');
 
           rerender(<Test formValue="key" />);