fix: sync controlled ComboBox selection state (#22167)

adamalston · web-flow · commit 1e2d9cd2a9e1 · 2026-05-27T09:01:23.000Z
diff --git a/packages/react/src/components/ComboBox/ComboBox-test.js b/packages/react/src/components/ComboBox/ComboBox-test.js
@@ -819,6 +819,29 @@ describe('ComboBox', () => {
         `${prefix}--list-box__menu-item--active`
       );
     });
+
+    it('should keep the external selection when the menu closes after an external update', async () => {
+      render(<ControlledComboBox />);
+
+      await openMenu();
+      await userEvent.click(screen.getByRole('option', { name: 'Item 2' }));
+      expect(screen.getByText('onChangeCallCount: 1')).toBeInTheDocument();
+      expect(screen.getByTestId('selected-item').textContent).toBe('Item 2');
+
+      await userEvent.click(
+        screen.getByRole('button', { name: 'Choose item 3' })
+      );
+      expect(screen.getByText('onChangeCallCount: 2')).toBeInTheDocument();
+      expect(screen.getByTestId('selected-item').textContent).toBe('Item 3');
+
+      await openMenu();
+      await userEvent.click(document.body);
+
+      expect(screen.getByText('onChangeCallCount: 2')).toBeInTheDocument();
+      expect(screen.getByTestId('selected-item').textContent).toBe('Item 3');
+      expect(findInputNode()).toHaveDisplayValue('Item 3');
+    });
+
     it('should update and call `onChange` once when selection is updated externally', async () => {
       const { rerender } = render(
         <ComboBox {...mockProps} selectedItem={mockProps.items[0]} />
diff --git a/packages/react/src/components/ComboBox/ComboBox.tsx b/packages/react/src/components/ComboBox/ComboBox.tsx
@@ -510,6 +510,14 @@ const ComboBox = forwardRef(
     const prevSelectedItemProp = useRef<ItemType | null | undefined>(
       selectedItemProp
     );
+    const isSyncingControlledSelectionRef = useRef(false);
+    const pendingControlledSelectionRef = useRef<{
+      pending: boolean;
+      value: ItemType | null | undefined;
+    }>({
+      pending: false,
+      value: undefined,
+    });
 
     useEffect(() => {
       isManualClearingRef.current = isClearing;
@@ -523,6 +531,10 @@ const ComboBox = forwardRef(
     // fully controlled combobox: handle changes to selectedItemProp
     useEffect(() => {
       if (prevSelectedItemProp.current !== selectedItemProp) {
+        pendingControlledSelectionRef.current = {
+          pending: true,
+          value: selectedItemProp,
+        };
         const currentInputValue = getInputValue({
           initialSelectedItem,
           itemToString,
@@ -885,13 +897,17 @@ const ComboBox = forwardRef(
       isItemDisabled: isDisabledItem,
       ...downshiftProps,
       onStateChange: ({ type, selectedItem: newSelectedItem }) => {
+        if (
+          isManualClearingRef.current ||
+          isSyncingControlledSelectionRef.current
+        ) {
+          isSyncingControlledSelectionRef.current = false;
+          return;
+        }
         downshiftProps?.onStateChange?.({
           type,
           selectedItem: newSelectedItem,
         });
-        if (isManualClearingRef.current) {
-          return;
-        }
         if (
           (type === ItemClick ||
             type === FunctionSelectItem ||
@@ -914,6 +930,19 @@ const ComboBox = forwardRef(
     const currentSelectedItem =
       typeof selectedItemProp !== 'undefined' ? selectedItemProp : selectedItem;
 
+    useEffect(() => {
+      if (pendingControlledSelectionRef.current.pending) {
+        const { value } = pendingControlledSelectionRef.current;
+        const nextSelectedItem = typeof value === 'undefined' ? null : value;
+        pendingControlledSelectionRef.current.pending = false;
+
+        if (!isEqual(selectedItem, nextSelectedItem)) {
+          isSyncingControlledSelectionRef.current = true;
+          selectItem(nextSelectedItem);
+        }
+      }
+    }, [selectedItem, selectedItemProp, selectItem]);
+
     useEffect(() => {
       // Used to expose the downshift actions to consumers for use with downshiftProps
       // An odd pattern, here we mutate the value stored in the ref provided from the consumer.
