feat: add modal prop to Combobox Root

Allows callers to opt out of the default modal behaviour where outside
elements are aria-hidden, page scroll is locked, and focus is trapped
in the trigger. Setting modal={false} is useful when the combobox sits
inside a dialog or other focus-managing container that already handles
these concerns, or when the product deliberately needs pointer events
outside the open listbox to remain active.

Default remains true so existing usage is unaffected.

Author: gaurav-init

packages/primitives/src/components/Combobox/Combobox.test.tsx

@@ -987,4 +987,33 @@ describe('Combobox', () => {
       expect(getByText('No value found')).toBeInTheDocument();
     });
   });
+
+  describe('modal prop', () => {
+    it('should open the listbox when modal is false', async () => {
+      const { getByRole, user } = render({ modal: false });
+
+      await user.click(getByRole('combobox'));
+
+      expect(getByRole('listbox')).toBeInTheDocument();
+    });
+
+    it('should close the listbox on Escape when modal is false', async () => {
+      const { getByRole, queryByRole, user } = render({ modal: false });
+
+      await user.click(getByRole('combobox'));
+      expect(getByRole('listbox')).toBeInTheDocument();
+
+      await user.keyboard('[Escape]');
+      expect(queryByRole('listbox')).not.toBeInTheDocument();
+    });
+
+    it('should allow selecting an item when modal is false', async () => {
+      const { getByRole, user } = render({ modal: false });
+
+      await user.click(getByRole('combobox'));
+      await user.click(getByRole('option', { name: 'Option 1' }));
+
+      expect(getByRole('combobox')).toHaveValue('Option 1');
+    });
+  });
 });

packages/primitives/src/components/Combobox/Combobox.tsx

@@ -69,6 +69,7 @@ type ComboboxContextValue = {
   contentId: string;
   disabled?: boolean;
   locale: string;
+  modal: boolean;
   onOpenChange(open: boolean): void;
   onTriggerChange(node: ComboboxInputElement | null): void;
   onValueChange(value: string | undefined): void;
@@ -106,6 +107,13 @@ interface RootProps {
   defaultTextValue?: string;
   disabled?: boolean;
   locale?: string;
+  /**
+   * The modality of the combobox. When set to `true`, interaction with
+   * outside elements will be disabled and only the combobox content will
+   * be visible to screen readers.
+   * @default true
+   */
+  modal?: boolean;
   onOpenChange?(open: boolean): void;
   onValueChange?(value: string): void;
   onTextValueChange?(textValue: string): void;
@@ -177,6 +185,7 @@ const Combobox = (props: RootProps) => {
     disabled,
     required = false,
     locale = 'en-EN',
+    modal = true,
     onTextValueChange,
     textValue: textValueProp,
     defaultTextValue,
@@ -266,8 +275,8 @@ const Combobox = (props: RootProps) => {
 
   // aria-hide everything except the content (better supported equivalent to setting aria-modal)
   React.useEffect(() => {
-    if (content && trigger) return hideOthers([content, trigger]);
-  }, [content, trigger]);
+    if (modal && content && trigger) return hideOthers([content, trigger]);
+  }, [modal, content, trigger]);
 
   return (
     <ComboboxProviders>
@@ -284,6 +293,7 @@ const Combobox = (props: RootProps) => {
         onOpenChange={setOpen}
         disabled={disabled}
         locale={locale}
+        modal={modal}
         focusFirst={focusFirst}
         textValue={textValue}
         onTextValueChange={setTextValue}
@@ -330,7 +340,7 @@ const ComboboxTrigger = React.forwardRef<ComboboxTriggerElement, TriggerProps>((
         asChild
         // we make sure we're not trapping once it's been closed
         // (closed !== unmounted when animating out)
-        trapped={context.open}
+        trapped={context.modal && context.open}
         onMountAutoFocus={(event) => {
           // we prevent open autofocus because we manually focus the selected item
           event.preventDefault();
@@ -858,41 +868,41 @@ const ComboboxContentImpl = React.forwardRef<ComboboxContentImplElement, Combobo
       };
     }, [onOpenChange]);
 
-    return (
-      <RemoveScroll allowPinchZoom>
-        <DismissableLayer
-          asChild
-          onEscapeKeyDown={onEscapeKeyDown}
-          onPointerDownOutside={onPointerDownOutside}
-          // When focus is trapped, a focusout event may still happen.
-          // We make sure we don't trigger our `onDismiss` in such case.
-          onFocusOutside={(event) => {
-            event.preventDefault();
-          }}
-          onDismiss={() => {
-            context.onOpenChange(false);
-            context.trigger?.focus({ preventScroll: true });
+    const content = (
+      <DismissableLayer
+        asChild
+        onEscapeKeyDown={onEscapeKeyDown}
+        onPointerDownOutside={onPointerDownOutside}
+        // When focus is trapped, a focusout event may still happen.
+        // We make sure we don't trigger our `onDismiss` in such case.
+        onFocusOutside={(event) => {
+          event.preventDefault();
+        }}
+        onDismiss={() => {
+          context.onOpenChange(false);
+          context.trigger?.focus({ preventScroll: true });
+        }}
+      >
+        <ComboboxPopperPosition
+          role="listbox"
+          id={context.contentId}
+          data-state={context.open ? 'open' : 'closed'}
+          onContextMenu={(event) => event.preventDefault()}
+          {...contentProps}
+          ref={composedRefs}
+          style={{
+            // flex layout so we can place the scroll buttons properly
+            display: 'flex',
+            flexDirection: 'column',
+            // reset the outline by default as the content MAY get focused
+            outline: 'none',
+            ...contentProps.style,
           }}
-        >
-          <ComboboxPopperPosition
-            role="listbox"
-            id={context.contentId}
-            data-state={context.open ? 'open' : 'closed'}
-            onContextMenu={(event) => event.preventDefault()}
-            {...contentProps}
-            ref={composedRefs}
-            style={{
-              // flex layout so we can place the scroll buttons properly
-              display: 'flex',
-              flexDirection: 'column',
-              // reset the outline by default as the content MAY get focused
-              outline: 'none',
-              ...contentProps.style,
-            }}
-          />
-        </DismissableLayer>
-      </RemoveScroll>
+        />
+      </DismissableLayer>
     );
+
+    return context.modal ? <RemoveScroll allowPinchZoom>{content}</RemoveScroll> : content;
   },
 );