fix(overlay): fixing issues with teleported modals

Author: ShaneK

core/src/components/modal/gestures/sheet.ts

@@ -96,8 +96,9 @@ export const createSheetGesture = (
 
   const enableBackdrop = () => {
     // Respect explicit opt-out of focus trapping/backdrop interactions
-    // If focusTrap is false, do not enable the backdrop or re-enable focus trap
-    if ((baseEl as HTMLIonModalElement & { focusTrap?: boolean }).focusTrap === false) {
+    // If focusTrap is false or showBackdrop is false, do not enable the backdrop or re-enable focus trap
+    const el = baseEl as HTMLIonModalElement & { focusTrap?: boolean; showBackdrop?: boolean };
+    if (el.focusTrap === false || el.showBackdrop === false) {
       return;
     }
     baseEl.style.setProperty('pointer-events', 'auto');
@@ -242,7 +243,8 @@ export const createSheetGesture = (
      */
     const shouldEnableBackdrop =
       currentBreakpoint > backdropBreakpoint &&
-      (baseEl as HTMLIonModalElement & { focusTrap?: boolean }).focusTrap !== false;
+      (baseEl as HTMLIonModalElement & { focusTrap?: boolean }).focusTrap !== false &&
+      (baseEl as HTMLIonModalElement & { showBackdrop?: boolean }).showBackdrop !== false;
     if (shouldEnableBackdrop) {
       enableBackdrop();
     } else {
@@ -591,7 +593,8 @@ export const createSheetGesture = (
                    */
                   const shouldEnableBackdrop =
                     currentBreakpoint > backdropBreakpoint &&
-                    (baseEl as HTMLIonModalElement & { focusTrap?: boolean }).focusTrap !== false;
+                    (baseEl as HTMLIonModalElement & { focusTrap?: boolean }).focusTrap !== false &&
+                    (baseEl as HTMLIonModalElement & { showBackdrop?: boolean }).showBackdrop !== false;
                   if (shouldEnableBackdrop) {
                     enableBackdrop();
                   } else {

core/src/utils/overlays.ts

@@ -494,10 +494,8 @@ export const setRootAriaHidden = (hidden = false) => {
 
   if (hidden) {
     viewContainer.setAttribute('aria-hidden', 'true');
-    viewContainer.setAttribute('inert', '');
   } else {
     viewContainer.removeAttribute('aria-hidden');
-    viewContainer.removeAttribute('inert');
   }
 };
 
@@ -532,17 +530,34 @@ export const present = async <OverlayPresentOptions>(
    * the keyboard focus from leaving the overlay unless
    * developers explicitly opt out (for example, sheet
    * modals that should permit background interaction).
+   *
+   * Note: Some apps move inline overlays to a specific container
+   * during the willPresent lifecycle (e.g., React portals via
+   * onWillPresent). Defer applying aria-hidden/inert to the app
+   * root until after willPresent so we can detect where the
+   * overlay is finally inserted. If the overlay is inside the
+   * view container subtree, skip adding aria-hidden/inert there
+   * to avoid disabling the overlay.
    */
-  const overlayEl = overlay.el as HTMLIonOverlayElement & { focusTrap?: boolean };
+  const overlayEl = overlay.el as HTMLIonOverlayElement & { focusTrap?: boolean; showBackdrop?: boolean };
   const shouldTrapFocus = overlayEl.tagName !== 'ION-TOAST' && overlayEl.focusTrap !== false;
-
-  if (shouldTrapFocus) {
-    setRootAriaHidden(true);
-    document.body.classList.add(BACKDROP_NO_SCROLL);
-  }
+  // Only lock out root content when backdrop is active. Developers relying on showBackdrop=false
+  // expect background interaction to remain enabled.
+  const shouldLockRoot = shouldTrapFocus && overlayEl.showBackdrop !== false;
 
   overlay.presented = true;
   overlay.willPresent.emit();
+
+  if (shouldLockRoot) {
+    const root = getAppRoot(document);
+    const viewContainer = root.querySelector('ion-router-outlet, #ion-view-container-root');
+    const overlayInsideViewContainer = viewContainer ? viewContainer.contains(overlayEl) : false;
+
+    if (!overlayInsideViewContainer) {
+      setRootAriaHidden(true);
+    }
+    document.body.classList.add(BACKDROP_NO_SCROLL);
+  }
   overlay.willPresentShorthand?.emit();
 
   const mode = getIonMode(overlay);
@@ -664,18 +679,19 @@ export const dismiss = async <OverlayDismissOptions>(
    * from the root element when the last focus-trapping overlay
    * is dismissed.
    */
-  const overlaysTrappingFocus = presentedOverlays.filter(
-    (o) => o.tagName !== 'ION-TOAST' && (o as any).focusTrap !== false
-  );
-  const overlayEl = overlay.el as HTMLIonOverlayElement & { focusTrap?: boolean };
-  const trapsFocus = overlayEl.tagName !== 'ION-TOAST' && overlayEl.focusTrap !== false;
+  const overlaysLockingRoot = presentedOverlays.filter((o) => {
+    const el = o as HTMLIonOverlayElement & { focusTrap?: boolean; showBackdrop?: boolean };
+    return el.tagName !== 'ION-TOAST' && el.focusTrap !== false && el.showBackdrop !== false;
+  });
+  const overlayEl = overlay.el as HTMLIonOverlayElement & { focusTrap?: boolean; showBackdrop?: boolean };
+  const locksRoot = overlayEl.tagName !== 'ION-TOAST' && overlayEl.focusTrap !== false && overlayEl.showBackdrop !== false;
 
   /**
    * If this is the last visible overlay that is trapping focus
    * then we want to re-add the root to the accessibility tree.
    */
   const lastOverlayTrappingFocus =
-    trapsFocus && overlaysTrappingFocus.length === 1 && overlaysTrappingFocus[0].id === overlayEl.id;
+    locksRoot && overlaysLockingRoot.length === 1 && overlaysLockingRoot[0].id === overlayEl.id;
 
   if (lastOverlayTrappingFocus) {
     setRootAriaHidden(false);

packages/react/test/base/src/pages/overlay-components/ModalFocusTrap.tsx

@@ -0,0 +1,61 @@
+import React, { useState } from 'react';
+import { IonButton, IonContent, IonModal, IonPage } from '@ionic/react';
+
+const ModalFocusTrap: React.FC = () => {
+  const [showNonTrapped, setShowNonTrapped] = useState(false);
+  const [showTrapped, setShowTrapped] = useState(false);
+  const [count, setCount] = useState(0);
+
+  return (
+    <IonPage>
+      <IonContent className="ion-padding">
+        <IonButton id="open-non-trapped-modal" onClick={() => setShowNonTrapped(true)}>
+          Open Non-Trapped Sheet Modal
+        </IonButton>
+        <IonButton id="open-trapped-modal" color="primary" onClick={() => setShowTrapped(true)}>
+          Open Focus-Trapped Sheet Modal
+        </IonButton>
+
+        <IonButton id="background-action" onClick={() => setCount((c) => c + 1)}>
+          Background Action
+        </IonButton>
+        <div>
+          Background action count: <span id="background-action-count">{count}</span>
+        </div>
+
+        <IonModal
+          isOpen={showNonTrapped}
+          onDidDismiss={() => setShowNonTrapped(false)}
+          breakpoints={[0, 0.25, 0.5, 0.75, 1]}
+          initialBreakpoint={0.25}
+          backdropDismiss={false}
+          focusTrap={false}
+          handleBehavior="cycle"
+        >
+          <IonContent className="ion-padding">
+            <p>Non-trapped modal content</p>
+            <IonButton onClick={() => setShowNonTrapped(false)}>Close</IonButton>
+          </IonContent>
+        </IonModal>
+
+        <IonModal
+          isOpen={showTrapped}
+          onDidDismiss={() => setShowTrapped(false)}
+          breakpoints={[0, 0.25, 0.5, 0.75, 1]}
+          initialBreakpoint={0.5}
+          backdropDismiss={false}
+          focusTrap={true}
+          handleBehavior="cycle"
+        >
+          <IonContent className="ion-padding">
+            <p>Focus-trapped modal content</p>
+            <IonButton onClick={() => setShowTrapped(false)}>Close</IonButton>
+          </IonContent>
+        </IonModal>
+      </IonContent>
+    </IonPage>
+  );
+};
+
+export default ModalFocusTrap;
+

packages/react/test/base/src/pages/overlay-components/ModalTeleport.tsx

@@ -0,0 +1,71 @@
+import React, { useState } from 'react';
+import {
+  IonButton,
+  IonButtons,
+  IonContent,
+  IonHeader,
+  IonModal,
+  IonPage,
+  IonTitle,
+  IonToolbar,
+} from '@ionic/react';
+
+const ModalTeleport: React.FC = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  const [count, setCount] = useState(0);
+
+  return (
+    <IonPage>
+      <IonContent className="ion-padding">
+        <div id="example" style={{ minHeight: '40vh' }}></div>
+
+        <IonButton id="teleport-background-action" onClick={() => setCount((c) => c + 1)}>
+          Background Action
+        </IonButton>
+        <div>
+          Background action count: <span id="teleport-background-action-count">{count}</span>
+        </div>
+
+        <IonButton id="open-teleport-modal" onClick={() => setIsOpen(true)}>
+          Open Teleported Modal
+        </IonButton>
+
+        {isOpen && (
+          <IonModal
+            isOpen={true}
+            onDidDismiss={() => setIsOpen(false)}
+            onWillPresent={(event) => {
+              const container = document.getElementById('example');
+              if (container) {
+                container.appendChild(event.target as HTMLElement);
+              }
+            }}
+            breakpoints={[0.2, 0.5, 0.7]}
+            initialBreakpoint={0.5}
+            showBackdrop={false}
+          >
+            <IonHeader>
+              <IonToolbar>
+                <IonTitle>Modal</IonTitle>
+                <IonButtons slot="end">
+                  <IonButton id="close-teleport-modal" onClick={() => setIsOpen(false)}>
+                    Close
+                  </IonButton>
+                </IonButtons>
+              </IonToolbar>
+            </IonHeader>
+            <IonContent className="ion-padding">
+              <p>
+                Lorem ipsum dolor sit amet consectetur adipisicing elit. Magni illum quidem recusandae ducimus quos
+                reprehenderit. Veniam, molestias quos, dolorum consequuntur nisi deserunt omnis id illo sit cum qui.
+                Eaque, dicta.
+              </p>
+            </IonContent>
+          </IonModal>
+        )}
+      </IonContent>
+    </IonPage>
+  );
+};
+
+export default ModalTeleport;

packages/react/test/base/src/pages/overlay-components/OverlayComponents.tsx

@@ -14,6 +14,8 @@ import ActionSheetComponent from './ActionSheetComponent';
 import AlertComponent from './AlertComponent';
 import LoadingComponent from './LoadingComponent';
 import ModalComponent from './ModalComponent';
+import ModalFocusTrap from './ModalFocusTrap';
+import ModalTeleport from './ModalTeleport';
 import PickerComponent from './PickerComponent';
 import PopoverComponent from './PopoverComponent';
 import ToastComponent from './ToastComponent';
@@ -29,6 +31,8 @@ const OverlayHooks: React.FC<OverlayHooksProps> = () => {
         <Route path="/overlay-components/alert" component={AlertComponent} />
         <Route path="/overlay-components/loading" component={LoadingComponent} />
         <Route path="/overlay-components/modal" component={ModalComponent} />
+        <Route path="/overlay-components/modal-focus-trap" component={ModalFocusTrap} />
+        <Route path="/overlay-components/modal-teleport" component={ModalTeleport} />
         <Route path="/overlay-components/picker" component={PickerComponent} />
         <Route path="/overlay-components/popover" component={PopoverComponent} />
         <Route path="/overlay-components/toast" component={ToastComponent} />
@@ -50,6 +54,14 @@ const OverlayHooks: React.FC<OverlayHooksProps> = () => {
           <IonIcon icon={star} />
           <IonLabel>Modal</IonLabel>
         </IonTabButton>
+        <IonTabButton tab="modalFocus" href="/overlay-components/modal-focus-trap">
+          <IonIcon icon={star} />
+          <IonLabel>Modal Focus</IonLabel>
+        </IonTabButton>
+        <IonTabButton tab="modalTeleport" href="/overlay-components/modal-teleport">
+          <IonIcon icon={star} />
+          <IonLabel>Modal Teleport</IonLabel>
+        </IonTabButton>
         <IonTabButton tab="picker" href="/overlay-components/picker">
           <IonIcon icon={logoIonic} />
           <IonLabel>Picker</IonLabel>

packages/react/test/base/tests/e2e/specs/overlay-components/IonModalFocusTrap.cy.ts

@@ -0,0 +1,36 @@
+describe('IonModal: focusTrap regression', () => {
+  beforeEach(() => {
+    cy.visit('/overlay-components/modal-focus-trap');
+  });
+
+  it('should allow interacting with background when focusTrap=false', () => {
+    cy.get('#open-non-trapped-modal').click();
+    cy.get('ion-modal').should('be.visible');
+
+    cy.get('#background-action').click();
+    cy.get('#background-action-count').should('have.text', '1');
+  });
+
+  it('should prevent interacting with background when focusTrap=true', () => {
+    cy.get('#open-trapped-modal').click();
+    cy.get('ion-modal').should('be.visible');
+
+    // Ensure backdrop is active and capturing pointer events
+    cy.get('ion-backdrop').should('exist');
+    cy.get('ion-backdrop').should('have.css', 'pointer-events', 'auto');
+
+    // Baseline: counter is 0
+    cy.get('#background-action-count').should('have.text', '0');
+
+    // Click the center of the background button via body coordinates (topmost element will receive it)
+    cy.get('#background-action').then(($btn) => {
+      const rect = $btn[0].getBoundingClientRect();
+      const x = rect.left + rect.width / 2;
+      const y = rect.top + rect.height / 2;
+      cy.get('body').click(x, y);
+    });
+
+    // Counter should remain unchanged
+    cy.get('#background-action-count').should('have.text', '0');
+  });
+});

packages/react/test/base/tests/e2e/specs/overlay-components/IonModalTeleport.cy.ts

@@ -0,0 +1,27 @@
+describe('IonModal: inline teleport with showBackdrop=false', () => {
+  beforeEach(() => {
+    cy.visit('/overlay-components/modal-teleport');
+  });
+
+  it('should render and remain interactive when appended into a page container', () => {
+    cy.get('#open-teleport-modal').click();
+    cy.get('ion-modal').should('be.visible');
+
+    // Verify modal content is interactable: close button should dismiss the modal
+    cy.get('#close-teleport-modal').click();
+    cy.get('ion-modal').should('not.exist');
+  });
+
+  it('should allow background interaction when showBackdrop=false', () => {
+    cy.get('#open-teleport-modal').click();
+    cy.get('ion-modal').should('be.visible');
+
+    // Ensure the background button is clickable while modal is open
+    cy.get('#teleport-background-action').click();
+    cy.get('#teleport-background-action-count').should('have.text', '1');
+
+    // Cleanup
+    cy.get('#close-teleport-modal').click();
+    cy.get('ion-modal').should('not.exist');
+  });
+});