feat(ComboBox): clear on blur

Author: tenphi

src/components/fields/ComboBox/ComboBox.docs.mdx

@@ -34,6 +34,8 @@ A combobox component that combines a text input with a dropdown list, allowing u
 
 **shouldCommitOnBlur** - When `true` (default), custom values are committed when the input loses focus. When `false`, custom values only commit when Enter is pressed. Only applies when `allowsCustomValue` is enabled.
 
+**clearOnBlur** - When `true`, clears both the selection and input when the input loses focus. When `false` (default), the input reverts to showing the current selection. Only applies to non-custom-value mode. Useful for search-like scenarios where you want to reset after each interaction.
+
 **popoverTrigger** - Controls how the popover opens:
 - `input` (default) - Opens when user types
 - `focus` - Opens when input receives focus
@@ -217,6 +219,26 @@ const [inputValue, setInputValue] = useState('');
 </ComboBox>
 ```
 
+### Clear on Blur
+
+<Story of={ComboBoxStories.ClearOnBlur} />
+
+```jsx
+const [selectedKey, setSelectedKey] = useState(null);
+
+<ComboBox
+  clearOnBlur
+  label="Fruit"
+  placeholder="Select a fruit..."
+  selectedKey={selectedKey}
+  onSelectionChange={setSelectedKey}
+>
+  <ComboBox.Item key="apple">Apple</ComboBox.Item>
+  <ComboBox.Item key="banana">Banana</ComboBox.Item>
+  <ComboBox.Item key="cherry">Cherry</ComboBox.Item>
+</ComboBox>
+```
+
 ### With Sections
 
 <Story of={ComboBoxStories.WithSections} />

src/components/fields/ComboBox/ComboBox.stories.tsx

@@ -73,6 +73,14 @@ const meta = {
         defaultValue: { summary: true },
       },
     },
+    clearOnBlur: {
+      control: { type: 'boolean' },
+      description:
+        'Whether to clear selection and input on blur (only applies to non-custom-value mode)',
+      table: {
+        defaultValue: { summary: false },
+      },
+    },
     isClearable: {
       control: { type: 'boolean' },
       description:
@@ -334,6 +342,37 @@ export const Clearable = () => (
   </ComboBox>
 );
 
+export const ClearOnBlur = () => {
+  const [selectedKey, setSelectedKey] = useState<string | null>(null);
+
+  return (
+    <div>
+      <ComboBox
+        clearOnBlur
+        label="Fruit"
+        placeholder="Select a fruit..."
+        selectedKey={selectedKey}
+        onSelectionChange={setSelectedKey}
+      >
+        <ComboBox.Item key="apple">Apple</ComboBox.Item>
+        <ComboBox.Item key="banana">Banana</ComboBox.Item>
+        <ComboBox.Item key="cherry">Cherry</ComboBox.Item>
+        <ComboBox.Item key="date">Date</ComboBox.Item>
+      </ComboBox>
+      <div style={{ marginTop: '16px' }}>
+        <div>
+          Selected: <strong>{selectedKey || 'none'}</strong>
+        </div>
+        <div style={{ fontSize: '12px', color: '#666', marginTop: '8px' }}>
+          With clearOnBlur, selection and input are cleared when the input loses
+          focus. This is useful for search-like scenarios where you want to
+          reset after each interaction.
+        </div>
+      </div>
+    </div>
+  );
+};
+
 export const WithSections = () => (
   <ComboBox label="Food" placeholder="Select food...">
     <ComboBox.Section key="fruits" title="Fruits">

src/components/fields/ComboBox/ComboBox.test.tsx

@@ -463,6 +463,128 @@ describe('<ComboBox />', () => {
     });
   });
 
+  it('should clear selection on blur when clearOnBlur is true', async () => {
+    const onSelectionChange = jest.fn();
+
+    const { getByRole, getAllByRole, queryByRole } = renderWithRoot(
+      <ComboBox clearOnBlur label="test" onSelectionChange={onSelectionChange}>
+        {items.map((item) => (
+          <ComboBox.Item key={item.key}>{item.children}</ComboBox.Item>
+        ))}
+      </ComboBox>,
+    );
+
+    const combobox = getByRole('combobox');
+
+    // Type to filter and open popover
+    await userEvent.type(combobox, 're');
+
+    await waitFor(() => {
+      expect(queryByRole('listbox')).toBeInTheDocument();
+    });
+
+    // Click on first option (Red)
+    const options = getAllByRole('option');
+    await userEvent.click(options[0]);
+
+    // Verify selection was made
+    await waitFor(() => {
+      expect(onSelectionChange).toHaveBeenCalledWith('red');
+      expect(combobox).toHaveValue('Red');
+    });
+
+    // Blur the input
+    await act(async () => {
+      combobox.blur();
+    });
+
+    // Should clear selection on blur
+    await waitFor(() => {
+      expect(onSelectionChange).toHaveBeenCalledWith(null);
+      expect(combobox).toHaveValue('');
+    });
+  }, 15000);
+
+  it('should maintain selection on blur without clearOnBlur flag', async () => {
+    const onSelectionChange = jest.fn();
+
+    const { getByRole, getAllByRole, queryByRole } = renderWithRoot(
+      <ComboBox label="test" onSelectionChange={onSelectionChange}>
+        {items.map((item) => (
+          <ComboBox.Item key={item.key}>{item.children}</ComboBox.Item>
+        ))}
+      </ComboBox>,
+    );
+
+    const combobox = getByRole('combobox');
+
+    // Type to filter and open popover
+    await userEvent.type(combobox, 're');
+
+    await waitFor(() => {
+      expect(queryByRole('listbox')).toBeInTheDocument();
+    });
+
+    // Click on first option (Red)
+    const options = getAllByRole('option');
+    await userEvent.click(options[0]);
+
+    // Verify selection was made
+    await waitFor(() => {
+      expect(onSelectionChange).toHaveBeenCalledWith('red');
+      expect(combobox).toHaveValue('Red');
+    });
+
+    // Clear the mock to check no additional calls happen
+    onSelectionChange.mockClear();
+
+    // Blur the input
+    await act(async () => {
+      combobox.blur();
+    });
+
+    // Wait a bit to ensure state has settled
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    // Should maintain selection on blur (default behavior)
+    expect(onSelectionChange).not.toHaveBeenCalled();
+    expect(combobox).toHaveValue('Red');
+  }, 15000);
+
+  it('should not apply clearOnBlur in allowsCustomValue mode', async () => {
+    const onSelectionChange = jest.fn();
+
+    const { getByRole } = renderWithRoot(
+      <ComboBox
+        allowsCustomValue
+        clearOnBlur
+        label="test"
+        onSelectionChange={onSelectionChange}
+      >
+        {items.map((item) => (
+          <ComboBox.Item key={item.key}>{item.children}</ComboBox.Item>
+        ))}
+      </ComboBox>,
+    );
+
+    const combobox = getByRole('combobox');
+
+    // Type custom value
+    await userEvent.type(combobox, 'Custom Value');
+
+    // Blur without pressing Enter - should commit the custom value
+    await act(async () => {
+      combobox.blur();
+    });
+
+    // In allowsCustomValue mode, clearOnBlur should not apply
+    // Instead, shouldCommitOnBlur (default: true) behavior should apply
+    await waitFor(() => {
+      expect(onSelectionChange).toHaveBeenCalledWith('Custom Value');
+      expect(combobox).toHaveValue('Custom Value');
+    });
+  });
+
   it('should show all items when opening with no results', async () => {
     const { getByRole, getAllByRole, queryByRole, getByTestId } =
       renderWithRoot(

src/components/fields/ComboBox/ComboBox.tsx

@@ -153,6 +153,8 @@ export interface CubeComboBoxProps<T>
   allowsCustomValue?: boolean;
   /** Whether to commit custom value on blur in allowsCustomValue mode (default: true) */
   shouldCommitOnBlur?: boolean;
+  /** Whether to clear selection and input on blur (default: false, only applies to non-custom-value mode) */
+  clearOnBlur?: boolean;
   /** Whether the combobox is clearable using ESC key or clear button */
   isClearable?: boolean;
   /** Callback called when the clear button is pressed */
@@ -913,6 +915,7 @@ export const ComboBox = forwardRef(function ComboBox<T extends object>(
     placeholder,
     allowsCustomValue,
     shouldCommitOnBlur = true,
+    clearOnBlur,
     items,
     children: renderChildren,
     sectionStyles,
@@ -1269,6 +1272,19 @@ export const ComboBox = forwardRef(function ComboBox<T extends object>(
       return;
     }
 
+    // In clearOnBlur mode (only for non-custom-value mode), clear selection and input
+    if (clearOnBlur && !allowsCustomValue) {
+      externalOnSelectionChange?.(null);
+      if (!isControlledKey) {
+        setInternalSelectedKey(null);
+      }
+      if (!isControlledInput) {
+        setInternalInputValue('');
+      }
+      onInputChange?.('');
+      return;
+    }
+
     // Reset input to show current selection (or empty if none)
     const nextValue =
       effectiveSelectedKey != null ? getItemLabel(effectiveSelectedKey) : '';