From e6353303b019f0258314864ff21e90a747b0fc66 Mon Sep 17 00:00:00 2001
From: Omar De Los Santos <omar.delossantos@zapier.com>
Date: Wed, 8 Jul 2026 08:20:49 -0700
Subject: [PATCH 1/3] Support modal mode in useComboBox

---
 .../react-aria/docs/combobox/useComboBox.mdx  | 21 ++++++
 .../react-aria/src/combobox/useComboBox.ts    | 24 ++++++-
 .../stories/combobox/useComboBox.stories.tsx  | 32 ++++++++-
 .../test/combobox/useComboBox.test.js         | 68 +++++++++++++++++++
 4 files changed, 141 insertions(+), 4 deletions(-)

diff --git a/packages/react-aria/docs/combobox/useComboBox.mdx b/packages/react-aria/docs/combobox/useComboBox.mdx
index 788042ec84e..6395321a382 100644
--- a/packages/react-aria/docs/combobox/useComboBox.mdx
+++ b/packages/react-aria/docs/combobox/useComboBox.mdx
@@ -674,6 +674,27 @@ function AsyncLoadingExample() {
 
 By default, interacting with an item in a ComboBox selects it and updates the input value. Alternatively, items may be links to another page or website. This can be achieved by passing the `href` prop to the `<Item>` component. Interacting with link items navigates to the provided URL and does not update the selection or input value. See the [links](../ListBox/useListBox.html#links) section in the `useListBox` docs for details on how to support this.
 
+### Modal
+
+While the ComboBox popover is open, `useComboBox` always hides the content outside the input and popup
+from assistive technologies. This preserves the behavior described in the
+[building a ComboBox blog post](https://react-aria.adobe.com/blog/building-a-combobox#portals), where
+the surrounding page is hidden so that screen reader users can easily navigate to the popover.
+
+By default (`isNonModal: true`), content is hidden using the
+[aria-hidden](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden)
+attribute. Set `isNonModal={false}` for a fully modal experience, where outside content receives the
+[inert](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/inert) attribute instead. The attribute
+prevents pointer and keyboard interaction with the hidden content.
+
+```tsx
+<ComboBox label="Favorite Animal" isNonModal={false}>
+  <Item key="red panda">Red Panda</Item>
+  <Item key="cat">Cat</Item>
+  <Item key="dog">Dog</Item>
+</ComboBox>
+```
+
 ## Internationalization
 
 `useComboBox` handles some aspects of internationalization automatically.
diff --git a/packages/react-aria/src/combobox/useComboBox.ts b/packages/react-aria/src/combobox/useComboBox.ts
index a1e3444817c..2de53e2cb1c 100644
--- a/packages/react-aria/src/combobox/useComboBox.ts
+++ b/packages/react-aria/src/combobox/useComboBox.ts
@@ -86,6 +86,18 @@ export interface AriaComboBoxOptions<T, M extends SelectionMode = 'single'> exte
    * virtualized scrolling.
    */
   layoutDelegate?: LayoutDelegate;
+  /**
+   * Whether elements outside the combobox popover are hidden from assistive
+   * technologies.
+   *
+   * While the popover is open, content outside the input and popover is always
+   * hidden. By default this applies `aria-hidden` to those elemenst. Set to
+   * `false` to use `inert`, which prevents pointer and keyboard interaction with
+   * the hidden content.
+   *
+   * @default true
+   */
+  isNonModal?: boolean;
 }
 
 export interface ComboBoxAria<T> extends ValidationResult {
@@ -127,7 +139,8 @@ export function useComboBox<T, M extends SelectionMode = 'single'>(
     // completionMode = 'suggest',
     shouldFocusWrap,
     isReadOnly,
-    isDisabled
+    isDisabled,
+    isNonModal = true
   } = props;
   let backupBtnRef = useRef(null);
   buttonRef = buttonRef ?? backupBtnRef;
@@ -449,10 +462,15 @@ export function useComboBox<T, M extends SelectionMode = 'single'>(
   useEffect(() => {
     if (state.isOpen) {
       return ariaHideOutside(
-        [inputRef.current, popoverRef.current].filter(element => element != null)
+        [inputRef.current, popoverRef.current].filter(element => element != null),
+        // Outside elements should always have `aria-hidden` while the popover is
+        // open to allow screen readers to immediately navigate to portalled popover.
+        // If `isNonModal` is false, we instead use `inert` to prevent pointer and
+        // keyboard interaction with the hidden content.
+        { shouldUseInert: !isNonModal }
       );
     }
-  }, [state.isOpen, inputRef, popoverRef]);
+  }, [state.isOpen, isNonModal, inputRef, popoverRef]);
 
   useUpdateEffect(() => {
     // Re-show focus ring when there is no virtually focused item.
diff --git a/packages/react-aria/stories/combobox/useComboBox.stories.tsx b/packages/react-aria/stories/combobox/useComboBox.stories.tsx
index 3b622ea24f1..65a1f87fb5e 100644
--- a/packages/react-aria/stories/combobox/useComboBox.stories.tsx
+++ b/packages/react-aria/stories/combobox/useComboBox.stories.tsx
@@ -27,7 +27,7 @@ for (let i = 0; i < 50; i++) {
   lotsOfItems.push({name: 'Item ' + i});
 }
 
-const Template = (args: AriaComboBoxProps<any>): JSX.Element => (
+const Template = (args: AriaComboBoxProps<any> & {isNonModal?: boolean}): JSX.Element => (
   <ComboBox {...args} label="Example" defaultItems={lotsOfItems}>
     {(item: any) => <Item key={item.name}>{item.name}</Item>}
   </ComboBox>
@@ -47,3 +47,33 @@ export const FocusWrapping: TemplateStory = {
   render: Template,
   args: {shouldFocusWrap: true}
 };
+
+export const Modal: TemplateStory = {
+  render: (args: AriaComboBoxProps<any> & {isNonModal?: boolean}): JSX.Element => (
+    <div>
+      <p>
+        <a href="//example.com">Content before</a> — inert while the list is open
+      </p>
+      <Template {...args} />
+      <p>
+        <a href="//example.com">Content after</a> — inert while the list is open
+      </p>
+    </div>
+  ),
+  args: {isNonModal: false}
+};
+
+export const NonModal: TemplateStory = {
+  render: (args: AriaComboBoxProps<any> & {isNonModal?: boolean}): JSX.Element => (
+    <div>
+      <p>
+        <a href="//example.com">Content before</a> — hidden (but interactive) while the list is open
+      </p>
+      <Template {...args} />
+      <p>
+        <a href="//example.com">Content after</a> — hidden (but interactive) while the list is open
+      </p>
+    </div>
+  ),
+  args: {isNonModal: true}
+};
diff --git a/packages/react-aria/test/combobox/useComboBox.test.js b/packages/react-aria/test/combobox/useComboBox.test.js
index 62d2511adb4..5e3af368e84 100644
--- a/packages/react-aria/test/combobox/useComboBox.test.js
+++ b/packages/react-aria/test/combobox/useComboBox.test.js
@@ -198,4 +198,72 @@ describe('useComboBox', function () {
 
     expect(onBlurMock).toHaveBeenCalledTimes(1);
   });
+
+  // While the popover is open, content outside the input and popover is always hidden.
+  // Note: jsdom does not support the `inert` property, so `shouldUseInert` falls back to
+  // `aria-hidden` here. The real `inert` behavior is validated in the browser/e2e tests.
+  describe('ariaHideOutside behavior', function () {
+    let inputEl, popoverEl, siblingEl;
+
+    beforeEach(() => {
+      inputEl = document.createElement('input');
+      popoverEl = document.createElement('div');
+      siblingEl = document.createElement('div');
+      siblingEl.textContent = 'outside content';
+      document.body.appendChild(inputEl);
+      document.body.appendChild(popoverEl);
+      document.body.appendChild(siblingEl);
+    });
+
+    afterEach(() => {
+      inputEl.remove();
+      popoverEl.remove();
+      siblingEl.remove();
+    });
+
+    let renderOpenComboBox = extraProps => {
+      let hookProps = {
+        ...defaultProps,
+        ...props,
+        ...extraProps,
+        inputRef: {current: inputEl},
+        popoverRef: {current: popoverEl}
+      };
+      let {result: state} = renderHook(p => useComboBoxState(p), {initialProps: hookProps});
+      act(() => {
+        state.current.open();
+      });
+      return renderHook(p => useComboBox(p, state.current), {initialProps: hookProps});
+    };
+
+    it('hides outside elements by default, keeping the input and popover visible', function () {
+      renderOpenComboBox();
+
+      expect(siblingEl).toHaveAttribute('aria-hidden', 'true');
+      expect(inputEl).not.toHaveAttribute('aria-hidden');
+      expect(popoverEl).not.toHaveAttribute('aria-hidden');
+    });
+
+    it('hides outside elements when isNonModal is true', function () {
+      renderOpenComboBox({isNonModal: true});
+
+      expect(siblingEl).toHaveAttribute('aria-hidden', 'true');
+      expect(inputEl).not.toHaveAttribute('aria-hidden');
+      expect(popoverEl).not.toHaveAttribute('aria-hidden');
+    });
+
+    it('hides outside elements when isNonModal is false', function () {
+      let {unmount} = renderOpenComboBox({isNonModal: false});
+
+      expect(siblingEl).toHaveAttribute('aria-hidden', 'true');
+      expect(inputEl).not.toHaveAttribute('aria-hidden');
+      expect(popoverEl).not.toHaveAttribute('aria-hidden');
+
+      act(() => {
+        unmount();
+      });
+
+      expect(siblingEl).not.toHaveAttribute('aria-hidden');
+    });
+  });
 });

From b896a0f44503809f5b606058a9a6600c0fd2c28c Mon Sep 17 00:00:00 2001
From: Omar De Los Santos <omar.delossantos@zapier.com>
Date: Wed, 8 Jul 2026 08:21:10 -0700
Subject: [PATCH 2/3] Support modal mode in Combobox

---
 .../react-aria-components/docs/ComboBox.mdx   | 16 +++++
 .../react-aria-components/src/ComboBox.tsx    |  6 ++
 .../stories/ComboBox.stories.tsx              | 58 +++++++++++++++++++
 .../test/ComboBox.test.js                     | 42 ++++++++++++++
 .../react-aria/stories/combobox/example.tsx   |  2 +-
 .../test/combobox/useComboBox.test.js         |  2 +-
 6 files changed, 124 insertions(+), 2 deletions(-)

diff --git a/packages/react-aria-components/docs/ComboBox.mdx b/packages/react-aria-components/docs/ComboBox.mdx
index 0751df477b3..07fa6696fc1 100644
--- a/packages/react-aria-components/docs/ComboBox.mdx
+++ b/packages/react-aria-components/docs/ComboBox.mdx
@@ -1178,6 +1178,22 @@ The `description` slot can be used to associate additional help text with a Comb
 
 </details>
 
+## Modal
+
+While the popover is open, ComboBox hides content outside the input and popover from
+assistive technologies so that screen readers can easily navigate to the portalled popover.
+By default this uses the `aria-hidden` attribute. Set `isNonModal={false}` for a fully modal
+experience, where outside content receives the [inert](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/inert)
+attribute instead, preventing pointer and keyboard interaction with the hidden content.
+
+```tsx
+<ComboBox isNonModal={false}>
+  <Item key="red panda">Red Panda</Item>
+  <Item key="cat">Cat</Item>
+  <Item key="dog">Dog</Item>
+</ComboBox>
+```
+
 ## Props
 
 ### ComboBox
diff --git a/packages/react-aria-components/src/ComboBox.tsx b/packages/react-aria-components/src/ComboBox.tsx
index 14502016b6e..987f0b4af99 100644
--- a/packages/react-aria-components/src/ComboBox.tsx
+++ b/packages/react-aria-components/src/ComboBox.tsx
@@ -130,6 +130,12 @@ export interface ComboBoxProps<T, M extends SelectionMode = 'single'>
   formValue?: 'text' | 'key';
   /** Whether the combo box allows the menu to be open when the collection is empty. */
   allowsEmptyCollection?: boolean;
+  /**
+   * Whether the popover is non-modal, i.e. elements outside the popover may be interacted with by assistive technologies.
+   *
+   * @default true
+   */
+  isNonModal?: boolean;
 }
 
 export const ComboBoxContext =
diff --git a/packages/react-aria-components/stories/ComboBox.stories.tsx b/packages/react-aria-components/stories/ComboBox.stories.tsx
index 0afe1168d49..e0a228dcd4c 100644
--- a/packages/react-aria-components/stories/ComboBox.stories.tsx
+++ b/packages/react-aria-components/stories/ComboBox.stories.tsx
@@ -590,3 +590,61 @@ export const InModal: ComboBoxStory = () => (
     </ModalOverlay>
   </DialogTrigger>
 );
+
+export const ModalComboBox: ComboBoxStory = () => (
+  <div>
+    <p>
+      <a href="//example.com">Content before</a> — inert while the list is open
+    </p>
+    <ComboBox name="modal-combo-box" isNonModal={false}>
+      <Label style={{display: 'block'}}>Test</Label>
+      <div style={{display: 'flex'}}>
+        <Input />
+        <Button>
+          <span aria-hidden="true" style={{padding: '0 2px'}}>
+            ▼
+          </span>
+        </Button>
+      </div>
+      <Popover>
+        <ListBox className={styles.menu} style={{width: 'var(--trigger-width)'}}>
+          <MyListBoxItem>Foo</MyListBoxItem>
+          <MyListBoxItem>Bar</MyListBoxItem>
+          <MyListBoxItem>Baz</MyListBoxItem>
+        </ListBox>
+      </Popover>
+    </ComboBox>
+    <p>
+      <a href="//example.com">Content after</a> — inert while the list is open
+    </p>
+  </div>
+);
+
+export const NonModalComboBox: ComboBoxStory = () => (
+  <div>
+    <p>
+      <a href="//example.com">Content before</a> — hidden (but interactive) while the list is open
+    </p>
+    <ComboBox name="non-modal-combo-box" isNonModal={true}>
+      <Label style={{display: 'block'}}>Test</Label>
+      <div style={{display: 'flex'}}>
+        <Input />
+        <Button>
+          <span aria-hidden="true" style={{padding: '0 2px'}}>
+            ▼
+          </span>
+        </Button>
+      </div>
+      <Popover>
+        <ListBox className={styles.menu} style={{width: 'var(--trigger-width)'}}>
+          <MyListBoxItem>Foo</MyListBoxItem>
+          <MyListBoxItem>Bar</MyListBoxItem>
+          <MyListBoxItem>Baz</MyListBoxItem>
+        </ListBox>
+      </Popover>
+    </ComboBox>
+    <p>
+      <a href="//example.com">Content after</a> — hidden (but interactive) while the list is open
+    </p>
+  </div>
+);
diff --git a/packages/react-aria-components/test/ComboBox.test.js b/packages/react-aria-components/test/ComboBox.test.js
index dfa993ecef8..df402224a68 100644
--- a/packages/react-aria-components/test/ComboBox.test.js
+++ b/packages/react-aria-components/test/ComboBox.test.js
@@ -114,6 +114,48 @@ describe('ComboBox', () => {
     expect(combobox).toHaveAttribute('aria-label', 'test');
   });
 
+  // While the popover is open, content outside the input and popover is hidden.
+  // Note: jsdom does not support the `inert` property, so `isNonModal={false}` falls back
+  // to `aria-hidden` here.
+  describe('isNonModal', () => {
+    let renderWithOutside = props =>
+      render(
+        <>
+          <a href="//example.com" data-testid="outside">
+            Outside link
+          </a>
+          <TestComboBox {...props} />
+        </>
+      );
+
+    it('hides outside elements with aria-hidden by default when open', async () => {
+      let {getByRole, getByTestId} = renderWithOutside();
+      let outside = getByTestId('outside');
+      let input = getByRole('combobox');
+
+      await user.click(getByRole('button'));
+
+      expect(getByRole('listbox')).toBeInTheDocument();
+      expect(outside).toHaveAttribute('aria-hidden', 'true');
+      expect(input).not.toHaveAttribute('aria-hidden');
+
+      await user.keyboard('{Escape}');
+      expect(outside).not.toHaveAttribute('aria-hidden');
+    });
+
+    it('hides outside elements when isNonModal is false', async () => {
+      let {getByRole, getByTestId} = renderWithOutside({isNonModal: false});
+      let outside = getByTestId('outside');
+      let input = getByRole('combobox');
+
+      await user.click(getByRole('button'));
+
+      expect(getByRole('listbox')).toBeInTheDocument();
+      expect(outside).toHaveAttribute('aria-hidden', 'true');
+      expect(input).not.toHaveAttribute('aria-hidden');
+    });
+  });
+
   it('should support custom render function', () => {
     let {getByRole} = render(
       <TestComboBox render={props => <div {...props} data-custom="true" />} />
diff --git a/packages/react-aria/stories/combobox/example.tsx b/packages/react-aria/stories/combobox/example.tsx
index 7a786b9ee78..ae540eab874 100644
--- a/packages/react-aria/stories/combobox/example.tsx
+++ b/packages/react-aria/stories/combobox/example.tsx
@@ -22,7 +22,7 @@ import {useListBox} from '../../src/listbox/useListBox';
 import {useOption} from '../../src/listbox/useOption';
 import {useOverlay} from '../../src/overlays/useOverlay';
 
-export function ComboBox(props: AriaComboBoxProps<any>): JSX.Element {
+export function ComboBox(props: AriaComboBoxProps<any> & {isNonModal?: boolean}): JSX.Element {
   // Setup filter function and state.
   let {contains} = useFilter({sensitivity: 'base'});
   let state = useComboBoxState({...props, defaultFilter: contains});
diff --git a/packages/react-aria/test/combobox/useComboBox.test.js b/packages/react-aria/test/combobox/useComboBox.test.js
index 5e3af368e84..e84845bde3e 100644
--- a/packages/react-aria/test/combobox/useComboBox.test.js
+++ b/packages/react-aria/test/combobox/useComboBox.test.js
@@ -201,7 +201,7 @@ describe('useComboBox', function () {
 
   // While the popover is open, content outside the input and popover is always hidden.
   // Note: jsdom does not support the `inert` property, so `shouldUseInert` falls back to
-  // `aria-hidden` here. The real `inert` behavior is validated in the browser/e2e tests.
+  // `aria-hidden` here.
   describe('ariaHideOutside behavior', function () {
     let inputEl, popoverEl, siblingEl;
 

From 183d3f1cb7929b47d975c59c866171f69ff07256 Mon Sep 17 00:00:00 2001
From: Omar De Los Santos <omar.delossantos@zapier.com>
Date: Wed, 8 Jul 2026 10:59:09 -0700
Subject: [PATCH 3/3] Lint code

---
 packages/react-aria-components/stories/ComboBox.stories.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react-aria-components/stories/ComboBox.stories.tsx b/packages/react-aria-components/stories/ComboBox.stories.tsx
index e0a228dcd4c..24aebea6414 100644
--- a/packages/react-aria-components/stories/ComboBox.stories.tsx
+++ b/packages/react-aria-components/stories/ComboBox.stories.tsx
@@ -625,7 +625,7 @@ export const NonModalComboBox: ComboBoxStory = () => (
     <p>
       <a href="//example.com">Content before</a> — hidden (but interactive) while the list is open
     </p>
-    <ComboBox name="non-modal-combo-box" isNonModal={true}>
+    <ComboBox name="non-modal-combo-box" isNonModal>
       <Label style={{display: 'block'}}>Test</Label>
       <div style={{display: 'flex'}}>
         <Input />