@ionic/core 8.8.5-nightly.20260427 → 8.8.5-nightly.20260428

package/dist/cjs/ion-modal.cjs.entry.js

@@ -1647,6 +1647,12 @@ const createSheetGesture = (baseEl, backdropEl, wrapperEl, initialBreakpoint, ba
 const MODAL_INSET_MIN_WIDTH = 768;
 const MODAL_INSET_MIN_HEIGHT = 600;
 const EDGE_THRESHOLD = 5;
+/**
+ * CSS values for `--width` / `--height` that are treated as fullscreen
+ * (modal touches the corresponding screen edges). Empty string means the
+ * property was not overridden. See `hasCustomModalDimensions()`.
+ */
+const FULLSCREEN_SIZE_VALUES = new Set(['', '100%', '100vw', '100vh', '100dvw', '100dvh', '100svw', '100svh']);
 /**
  * Cache for resolved root safe-area-top value, invalidated once per frame.
  */
@@ -1695,6 +1701,22 @@ const getRootSafeAreaTop = () => {
     }
     return value;
 };
+/**
+ * True when the modal host declares BOTH a non-fullscreen `--width` AND a
+ * non-fullscreen `--height` (i.e. a centered-dialog-like modal that doesn't
+ * touch any screen edge).
+ *
+ * The conservative "both axes" check avoids mis-zeroing safe-area for
+ * partial-custom modals where the modal still touches top/bottom edges
+ * (e.g. only `--width` overridden). Partial cases fall through to the
+ * existing position-based post-animation correction.
+ */
+const hasCustomModalDimensions = (hostEl) => {
+    const styles = getComputedStyle(hostEl);
+    const width = styles.getPropertyValue('--width').trim();
+    const height = styles.getPropertyValue('--height').trim();
+    return !FULLSCREEN_SIZE_VALUES.has(width) && !FULLSCREEN_SIZE_VALUES.has(height);
+};
 /**
  * Returns the initial safe-area configuration based on modal type.
  * This is called before animation starts and uses configuration-based prediction.
@@ -1729,8 +1751,11 @@ const getInitialSafeAreaConfig = (context) => {
     }
     // On viewports that meet the centered dialog media query breakpoints,
     // regular modals render as centered dialogs (not fullscreen), so they
-    // don't touch any screen edges and don't need safe-area insets.
-    if (isCenteredDialogViewport()) {
+    // don't touch any screen edges and don't need safe-area insets. Also
+    // applies to phone viewports when the modal declares custom --width and
+    // --height; these don't touch screen edges either, so the initial
+    // prediction must be zero to avoid a post-animation correction flash.
+    if (isCenteredDialogViewport() || context.hasCustomDimensions) {
         return {
             top: '0px',
             bottom: '0px',
@@ -2032,12 +2057,10 @@ const Modal = class {
             // since the viewport may have crossed the centered-dialog breakpoint.
             if (!context.isSheetModal && !context.isCardModal) {
                 this.updateSafeAreaOverrides();
-                // Re-evaluate fullscreen safe-area padding: clear first, then re-apply
-                if (this.wrapperEl) {
-                    this.wrapperEl.style.removeProperty('height');
-                    this.wrapperEl.style.removeProperty('padding-bottom');
-                }
-                this.applyFullscreenSafeArea();
+                // Re-evaluate fullscreen safe-area padding: clear first, then re-apply.
+                const { contentEl, hasFooter } = this.findContentAndFooter();
+                this.clearContentSafeAreaPadding(contentEl);
+                this.applyFullscreenSafeAreaTo(contentEl, hasFooter);
             }
         }, 50); // Debounce to avoid excessive calls during active resizing
     }
@@ -2784,6 +2807,11 @@ const Modal = class {
     }
     /**
      * Creates the context object for safe-area utilities.
+     *
+     * `hasCustomDimensions` is only set by `setInitialSafeAreaOverrides()`
+     * because it is only read by `getInitialSafeAreaConfig()`. Other callers
+     * (resize handler, post-animation update, fullscreen-padding apply) would
+     * pay a `getComputedStyle()` cost for a value they never consult.
      */
     getSafeAreaContext() {
         return {
@@ -2805,7 +2833,7 @@ const Modal = class {
      * sheets to prevent header content from getting double-offset padding).
      */
     setInitialSafeAreaOverrides() {
-        const context = this.getSafeAreaContext();
+        const context = Object.assign(Object.assign({}, this.getSafeAreaContext()), { hasCustomDimensions: hasCustomModalDimensions(this.el) });
         const safeAreaConfig = getInitialSafeAreaConfig(context);
         applySafeAreaOverrides(this.el, safeAreaConfig);
         // Set the internal offset property with the resolved root safe-area-top value
@@ -2845,59 +2873,85 @@ const Modal = class {
         applySafeAreaOverrides(el, safeAreaConfig);
     }
     /**
-     * Applies padding-bottom to fullscreen modal wrapper to prevent
-     * content from overlapping system navigation bar.
+     * Applies safe-area-bottom scroll padding to ion-content inside
+     * fullscreen modals that have no ion-footer. This prevents content
+     * from being hidden behind the system navigation bar while keeping
+     * the modal background edge-to-edge (no visible gap).
      */
     applyFullscreenSafeArea() {
-        const { wrapperEl, el } = this;
-        if (!wrapperEl)
-            return;
         const context = this.getSafeAreaContext();
         if (context.isSheetModal || context.isCardModal)
             return;
-        // Check for standard Ionic layout children (ion-content, ion-footer),
-        // searching one level deep for wrapped components (e.g.,
-        // <app-footer><ion-footer>...</ion-footer></app-footer>).
-        // Note: uses a manual loop instead of querySelector(':scope > ...') because
-        // Stencil's mock-doc (used in spec tests) does not support :scope.
-        let hasContent = false;
+        const { contentEl, hasFooter } = this.findContentAndFooter();
+        this.applyFullscreenSafeAreaTo(contentEl, hasFooter);
+    }
+    /**
+     * Sets --ion-content-safe-area-padding-bottom on the given ion-content
+     * when no footer is present, so ion-content's .inner-scroll includes
+     * safe-area-bottom in its scroll padding. This keeps the modal background
+     * edge-to-edge while ensuring content scrolls clear of the system nav bar.
+     *
+     * --ion-content-safe-area-padding-bottom is an internal CSS property used
+     * only by this code path. It is not part of ion-content's public API and
+     * should not be set by consumers. The default of 0px makes it a no-op
+     * when unset, which is the expected state for ion-content used outside of
+     * a fullscreen modal without a footer.
+     */
+    applyFullscreenSafeAreaTo(contentEl, hasFooter) {
+        // Only apply for standard Ionic layouts (has ion-content but no
+        // ion-footer). When a footer is present it handles its own safe-area
+        // padding. Custom modals with raw HTML are developer-controlled.
+        if (!contentEl || hasFooter)
+            return;
+        contentEl.style.setProperty('--ion-content-safe-area-padding-bottom', 'var(--ion-safe-area-bottom, 0px)');
+    }
+    /**
+     * Removes the internal --ion-content-safe-area-padding-bottom property
+     * from an already-located ion-content. Callers do their own
+     * findContentAndFooter() so they can also read hasFooter if needed.
+     */
+    clearContentSafeAreaPadding(contentEl) {
+        if (!contentEl)
+            return;
+        contentEl.style.removeProperty('--ion-content-safe-area-padding-bottom');
+    }
+    /**
+     * Finds ion-content and ion-footer among direct children and one level of
+     * grandchildren (for wrapped components like <app-footer><ion-footer>).
+     *
+     * Intentionally does NOT use findIonContent() or querySelector() because
+     * those search the full subtree and would match ion-content inside nested
+     * routes/pages. We only want direct slot children (+ one wrapper level).
+     *
+     * Uses a manual loop instead of querySelector(':scope > ...') because
+     * Stencil's mock-doc (used in spec tests) does not support :scope.
+     */
+    findContentAndFooter() {
+        let contentEl = null;
         let hasFooter = false;
-        for (const child of Array.from(el.children)) {
+        for (const child of Array.from(this.el.children)) {
             if (child.tagName === 'ION-CONTENT')
-                hasContent = true;
+                contentEl = child;
             if (child.tagName === 'ION-FOOTER')
                 hasFooter = true;
             for (const grandchild of Array.from(child.children)) {
-                if (grandchild.tagName === 'ION-CONTENT')
-                    hasContent = true;
+                if (grandchild.tagName === 'ION-CONTENT' && !contentEl)
+                    contentEl = grandchild;
                 if (grandchild.tagName === 'ION-FOOTER')
                     hasFooter = true;
             }
         }
-        // Only apply wrapper padding for standard Ionic layouts (has ion-content
-        // but no ion-footer). Custom modals with raw HTML are fully
-        // developer-controlled and should not be modified.
-        if (!hasContent || hasFooter)
-            return;
-        // Reduce wrapper height by safe-area and add equivalent padding so the
-        // total visual size stays the same but the flex content area shrinks.
-        // Using height + padding instead of box-sizing: border-box avoids
-        // breaking custom modals that set --border-width (border-box would
-        // include the border inside the height, changing the layout).
-        wrapperEl.style.setProperty('height', 'calc(var(--height) - var(--ion-safe-area-bottom, 0px))');
-        wrapperEl.style.setProperty('padding-bottom', 'var(--ion-safe-area-bottom, 0px)');
+        return { contentEl, hasFooter };
     }
     /**
-     * Clears all safe-area overrides and padding from wrapper.
+     * Clears all safe-area overrides and padding.
      */
     cleanupSafeAreaOverrides() {
         clearSafeAreaOverrides(this.el);
         // Remove internal sheet offset property
         this.el.style.removeProperty('--ion-modal-offset-top');
-        if (this.wrapperEl) {
-            this.wrapperEl.style.removeProperty('height');
-            this.wrapperEl.style.removeProperty('padding-bottom');
-        }
+        const { contentEl } = this.findContentAndFooter();
+        this.clearContentSafeAreaPadding(contentEl);
     }
     render() {
         const { handle, isSheetModal, presentingElement, htmlAttributes, handleBehavior, inheritedAttributes, focusTrap, expandToScroll, } = this;
@@ -2906,20 +2960,20 @@ const Modal = class {
         const isCardModal = presentingElement !== undefined && mode === 'ios';
         const isHandleCycle = handleBehavior === 'cycle';
         const isSheetModalWithHandle = isSheetModal && showHandle;
-        return (index$3.h(index$3.Host, Object.assign({ key: '1a53e8f87532abccc169ca4b24973a39c5f9ba16', "no-router": true,
+        return (index$3.h(index$3.Host, Object.assign({ key: '4bf38aa67df9a3f977163bba5423960bbafd16de', "no-router": true,
             // Allow the modal to be navigable when the handle is focusable
             tabIndex: isHandleCycle && isSheetModalWithHandle ? 0 : -1 }, htmlAttributes, { style: {
                 zIndex: `${20000 + this.overlayIndex}`,
-            }, class: Object.assign({ [mode]: true, ['modal-default']: !isCardModal && !isSheetModal, [`modal-card`]: isCardModal, [`modal-sheet`]: isSheetModal, [`modal-no-expand-scroll`]: isSheetModal && !expandToScroll, 'overlay-hidden': true, [overlays.FOCUS_TRAP_DISABLE_CLASS]: focusTrap === false }, theme.getClassMap(this.cssClass)), onIonBackdropTap: this.onBackdropTap, onIonModalDidPresent: this.onLifecycle, onIonModalWillPresent: this.onLifecycle, onIonModalWillDismiss: this.onLifecycle, onIonModalDidDismiss: this.onLifecycle, onFocus: this.onModalFocus }), index$3.h("ion-backdrop", { key: 'fa8e0a436c0d458331402e1850f87af3dc97b582', ref: (el) => (this.backdropEl = el), visible: this.showBackdrop, tappable: this.backdropDismiss, part: "backdrop" }), mode === 'ios' && index$3.h("div", { key: 'f00de6027d3c8b5bc93db3b0f7a50a87628d40bb', class: "modal-shadow" }), index$3.h("div", Object.assign({ key: 'ae5e33bd6c58e541edb2edbca92420ea02dd5175',
+            }, class: Object.assign({ [mode]: true, ['modal-default']: !isCardModal && !isSheetModal, [`modal-card`]: isCardModal, [`modal-sheet`]: isSheetModal, [`modal-no-expand-scroll`]: isSheetModal && !expandToScroll, 'overlay-hidden': true, [overlays.FOCUS_TRAP_DISABLE_CLASS]: focusTrap === false }, theme.getClassMap(this.cssClass)), onIonBackdropTap: this.onBackdropTap, onIonModalDidPresent: this.onLifecycle, onIonModalWillPresent: this.onLifecycle, onIonModalWillDismiss: this.onLifecycle, onIonModalDidDismiss: this.onLifecycle, onFocus: this.onModalFocus }), index$3.h("ion-backdrop", { key: '866da40cc5fc8d3e36637098fb3066a5bc9f4e0f', ref: (el) => (this.backdropEl = el), visible: this.showBackdrop, tappable: this.backdropDismiss, part: "backdrop" }), mode === 'ios' && index$3.h("div", { key: '5a2a05514ea8592c8feb0465e504aa7c7af17963', class: "modal-shadow" }), index$3.h("div", Object.assign({ key: '4d327115306451f57d190b06ab8cbb6191a6f1d7',
             /*
               role and aria-modal must be used on the
               same element. They must also be set inside the
               shadow DOM otherwise ion-button will not be highlighted
               when using VoiceOver: https://bugs.webkit.org/show_bug.cgi?id=247134
             */
-            role: "dialog" }, inheritedAttributes, { "aria-modal": "true", class: "modal-wrapper ion-overlay-wrapper", part: "content", ref: (el) => (this.wrapperEl = el) }), showHandle && (index$3.h("button", { key: '141cdd8f8522331f4b764e2a4d79ec6596b1eb3a', class: "modal-handle",
+            role: "dialog" }, inheritedAttributes, { "aria-modal": "true", class: "modal-wrapper ion-overlay-wrapper", part: "content", ref: (el) => (this.wrapperEl = el) }), showHandle && (index$3.h("button", { key: 'd1882835cc049232c0d957e3ba1e79676a07d179', class: "modal-handle",
             // Prevents the handle from receiving keyboard focus when it does not cycle
-            tabIndex: !isHandleCycle ? -1 : 0, "aria-label": "Activate to adjust the size of the dialog overlaying the screen", onClick: isHandleCycle ? this.onHandleClick : undefined, part: "handle", ref: (el) => (this.dragHandleEl = el) })), index$3.h("slot", { key: '7de20298b61abee67a16d275c9ebd9a25ce7dd26', onSlotchange: this.onSlotChange }))));
+            tabIndex: !isHandleCycle ? -1 : 0, "aria-label": "Activate to adjust the size of the dialog overlaying the screen", onClick: isHandleCycle ? this.onHandleClick : undefined, part: "handle", ref: (el) => (this.dragHandleEl = el) })), index$3.h("slot", { key: '81dc58b09cf7d7022b04cd170f53113604364d5e', onSlotchange: this.onSlotChange }))));
     }
     get el() { return index$3.getElement(this); }
     static get watchers() { return {

package/dist/collection/components/content/content.css

@@ -116,7 +116,7 @@
   -webkit-padding-end: var(--padding-end);
   padding-inline-end: var(--padding-end);
   padding-top: calc(var(--padding-top) + var(--offset-top));
-  padding-bottom: calc(var(--padding-bottom) + var(--keyboard-offset) + var(--offset-bottom));
+  padding-bottom: calc(var(--padding-bottom) + var(--keyboard-offset) + var(--offset-bottom) + var(--ion-content-safe-area-padding-bottom, 0px));
   position: absolute;
   color: var(--color);
   box-sizing: border-box;

package/dist/collection/components/modal/modal.js

@@ -21,7 +21,7 @@ import { mdEnterAnimation } from "./animations/md.enter";
 import { mdLeaveAnimation } from "./animations/md.leave";
 import { createSheetGesture } from "./gestures/sheet";
 import { createSwipeToCloseGesture, SwipeToCloseDefaults } from "./gestures/swipe-to-close";
-import { getInitialSafeAreaConfig, getPositionBasedSafeAreaConfig, applySafeAreaOverrides, clearSafeAreaOverrides, getRootSafeAreaTop, } from "./safe-area-utils";
+import { getInitialSafeAreaConfig, getPositionBasedSafeAreaConfig, applySafeAreaOverrides, clearSafeAreaOverrides, getRootSafeAreaTop, hasCustomModalDimensions, } from "./safe-area-utils";
 import { setCardStatusBarDark, setCardStatusBarDefault } from "./utils";
 // TODO(FW-2832): types
 /**
@@ -251,12 +251,10 @@ export class Modal {
             // since the viewport may have crossed the centered-dialog breakpoint.
             if (!context.isSheetModal && !context.isCardModal) {
                 this.updateSafeAreaOverrides();
-                // Re-evaluate fullscreen safe-area padding: clear first, then re-apply
-                if (this.wrapperEl) {
-                    this.wrapperEl.style.removeProperty('height');
-                    this.wrapperEl.style.removeProperty('padding-bottom');
-                }
-                this.applyFullscreenSafeArea();
+                // Re-evaluate fullscreen safe-area padding: clear first, then re-apply.
+                const { contentEl, hasFooter } = this.findContentAndFooter();
+                this.clearContentSafeAreaPadding(contentEl);
+                this.applyFullscreenSafeAreaTo(contentEl, hasFooter);
             }
         }, 50); // Debounce to avoid excessive calls during active resizing
     }
@@ -1011,6 +1009,11 @@ export class Modal {
     }
     /**
      * Creates the context object for safe-area utilities.
+     *
+     * `hasCustomDimensions` is only set by `setInitialSafeAreaOverrides()`
+     * because it is only read by `getInitialSafeAreaConfig()`. Other callers
+     * (resize handler, post-animation update, fullscreen-padding apply) would
+     * pay a `getComputedStyle()` cost for a value they never consult.
      */
     getSafeAreaContext() {
         return {
@@ -1032,7 +1035,7 @@ export class Modal {
      * sheets to prevent header content from getting double-offset padding).
      */
     setInitialSafeAreaOverrides() {
-        const context = this.getSafeAreaContext();
+        const context = Object.assign(Object.assign({}, this.getSafeAreaContext()), { hasCustomDimensions: hasCustomModalDimensions(this.el) });
         const safeAreaConfig = getInitialSafeAreaConfig(context);
         applySafeAreaOverrides(this.el, safeAreaConfig);
         // Set the internal offset property with the resolved root safe-area-top value
@@ -1072,59 +1075,85 @@ export class Modal {
         applySafeAreaOverrides(el, safeAreaConfig);
     }
     /**
-     * Applies padding-bottom to fullscreen modal wrapper to prevent
-     * content from overlapping system navigation bar.
+     * Applies safe-area-bottom scroll padding to ion-content inside
+     * fullscreen modals that have no ion-footer. This prevents content
+     * from being hidden behind the system navigation bar while keeping
+     * the modal background edge-to-edge (no visible gap).
      */
     applyFullscreenSafeArea() {
-        const { wrapperEl, el } = this;
-        if (!wrapperEl)
-            return;
         const context = this.getSafeAreaContext();
         if (context.isSheetModal || context.isCardModal)
             return;
-        // Check for standard Ionic layout children (ion-content, ion-footer),
-        // searching one level deep for wrapped components (e.g.,
-        // <app-footer><ion-footer>...</ion-footer></app-footer>).
-        // Note: uses a manual loop instead of querySelector(':scope > ...') because
-        // Stencil's mock-doc (used in spec tests) does not support :scope.
-        let hasContent = false;
+        const { contentEl, hasFooter } = this.findContentAndFooter();
+        this.applyFullscreenSafeAreaTo(contentEl, hasFooter);
+    }
+    /**
+     * Sets --ion-content-safe-area-padding-bottom on the given ion-content
+     * when no footer is present, so ion-content's .inner-scroll includes
+     * safe-area-bottom in its scroll padding. This keeps the modal background
+     * edge-to-edge while ensuring content scrolls clear of the system nav bar.
+     *
+     * --ion-content-safe-area-padding-bottom is an internal CSS property used
+     * only by this code path. It is not part of ion-content's public API and
+     * should not be set by consumers. The default of 0px makes it a no-op
+     * when unset, which is the expected state for ion-content used outside of
+     * a fullscreen modal without a footer.
+     */
+    applyFullscreenSafeAreaTo(contentEl, hasFooter) {
+        // Only apply for standard Ionic layouts (has ion-content but no
+        // ion-footer). When a footer is present it handles its own safe-area
+        // padding. Custom modals with raw HTML are developer-controlled.
+        if (!contentEl || hasFooter)
+            return;
+        contentEl.style.setProperty('--ion-content-safe-area-padding-bottom', 'var(--ion-safe-area-bottom, 0px)');
+    }
+    /**
+     * Removes the internal --ion-content-safe-area-padding-bottom property
+     * from an already-located ion-content. Callers do their own
+     * findContentAndFooter() so they can also read hasFooter if needed.
+     */
+    clearContentSafeAreaPadding(contentEl) {
+        if (!contentEl)
+            return;
+        contentEl.style.removeProperty('--ion-content-safe-area-padding-bottom');
+    }
+    /**
+     * Finds ion-content and ion-footer among direct children and one level of
+     * grandchildren (for wrapped components like <app-footer><ion-footer>).
+     *
+     * Intentionally does NOT use findIonContent() or querySelector() because
+     * those search the full subtree and would match ion-content inside nested
+     * routes/pages. We only want direct slot children (+ one wrapper level).
+     *
+     * Uses a manual loop instead of querySelector(':scope > ...') because
+     * Stencil's mock-doc (used in spec tests) does not support :scope.
+     */
+    findContentAndFooter() {
+        let contentEl = null;
         let hasFooter = false;
-        for (const child of Array.from(el.children)) {
+        for (const child of Array.from(this.el.children)) {
             if (child.tagName === 'ION-CONTENT')
-                hasContent = true;
+                contentEl = child;
             if (child.tagName === 'ION-FOOTER')
                 hasFooter = true;
             for (const grandchild of Array.from(child.children)) {
-                if (grandchild.tagName === 'ION-CONTENT')
-                    hasContent = true;
+                if (grandchild.tagName === 'ION-CONTENT' && !contentEl)
+                    contentEl = grandchild;
                 if (grandchild.tagName === 'ION-FOOTER')
                     hasFooter = true;
             }
         }
-        // Only apply wrapper padding for standard Ionic layouts (has ion-content
-        // but no ion-footer). Custom modals with raw HTML are fully
-        // developer-controlled and should not be modified.
-        if (!hasContent || hasFooter)
-            return;
-        // Reduce wrapper height by safe-area and add equivalent padding so the
-        // total visual size stays the same but the flex content area shrinks.
-        // Using height + padding instead of box-sizing: border-box avoids
-        // breaking custom modals that set --border-width (border-box would
-        // include the border inside the height, changing the layout).
-        wrapperEl.style.setProperty('height', 'calc(var(--height) - var(--ion-safe-area-bottom, 0px))');
-        wrapperEl.style.setProperty('padding-bottom', 'var(--ion-safe-area-bottom, 0px)');
+        return { contentEl, hasFooter };
     }
     /**
-     * Clears all safe-area overrides and padding from wrapper.
+     * Clears all safe-area overrides and padding.
      */
     cleanupSafeAreaOverrides() {
         clearSafeAreaOverrides(this.el);
         // Remove internal sheet offset property
         this.el.style.removeProperty('--ion-modal-offset-top');
-        if (this.wrapperEl) {
-            this.wrapperEl.style.removeProperty('height');
-            this.wrapperEl.style.removeProperty('padding-bottom');
-        }
+        const { contentEl } = this.findContentAndFooter();
+        this.clearContentSafeAreaPadding(contentEl);
     }
     render() {
         const { handle, isSheetModal, presentingElement, htmlAttributes, handleBehavior, inheritedAttributes, focusTrap, expandToScroll, } = this;
@@ -1133,20 +1162,20 @@ export class Modal {
         const isCardModal = presentingElement !== undefined && mode === 'ios';
         const isHandleCycle = handleBehavior === 'cycle';
         const isSheetModalWithHandle = isSheetModal && showHandle;
-        return (h(Host, Object.assign({ key: '1a53e8f87532abccc169ca4b24973a39c5f9ba16', "no-router": true,
+        return (h(Host, Object.assign({ key: '4bf38aa67df9a3f977163bba5423960bbafd16de', "no-router": true,
             // Allow the modal to be navigable when the handle is focusable
             tabIndex: isHandleCycle && isSheetModalWithHandle ? 0 : -1 }, htmlAttributes, { style: {
                 zIndex: `${20000 + this.overlayIndex}`,
-            }, class: Object.assign({ [mode]: true, ['modal-default']: !isCardModal && !isSheetModal, [`modal-card`]: isCardModal, [`modal-sheet`]: isSheetModal, [`modal-no-expand-scroll`]: isSheetModal && !expandToScroll, 'overlay-hidden': true, [FOCUS_TRAP_DISABLE_CLASS]: focusTrap === false }, getClassMap(this.cssClass)), onIonBackdropTap: this.onBackdropTap, onIonModalDidPresent: this.onLifecycle, onIonModalWillPresent: this.onLifecycle, onIonModalWillDismiss: this.onLifecycle, onIonModalDidDismiss: this.onLifecycle, onFocus: this.onModalFocus }), h("ion-backdrop", { key: 'fa8e0a436c0d458331402e1850f87af3dc97b582', ref: (el) => (this.backdropEl = el), visible: this.showBackdrop, tappable: this.backdropDismiss, part: "backdrop" }), mode === 'ios' && h("div", { key: 'f00de6027d3c8b5bc93db3b0f7a50a87628d40bb', class: "modal-shadow" }), h("div", Object.assign({ key: 'ae5e33bd6c58e541edb2edbca92420ea02dd5175',
+            }, class: Object.assign({ [mode]: true, ['modal-default']: !isCardModal && !isSheetModal, [`modal-card`]: isCardModal, [`modal-sheet`]: isSheetModal, [`modal-no-expand-scroll`]: isSheetModal && !expandToScroll, 'overlay-hidden': true, [FOCUS_TRAP_DISABLE_CLASS]: focusTrap === false }, getClassMap(this.cssClass)), onIonBackdropTap: this.onBackdropTap, onIonModalDidPresent: this.onLifecycle, onIonModalWillPresent: this.onLifecycle, onIonModalWillDismiss: this.onLifecycle, onIonModalDidDismiss: this.onLifecycle, onFocus: this.onModalFocus }), h("ion-backdrop", { key: '866da40cc5fc8d3e36637098fb3066a5bc9f4e0f', ref: (el) => (this.backdropEl = el), visible: this.showBackdrop, tappable: this.backdropDismiss, part: "backdrop" }), mode === 'ios' && h("div", { key: '5a2a05514ea8592c8feb0465e504aa7c7af17963', class: "modal-shadow" }), h("div", Object.assign({ key: '4d327115306451f57d190b06ab8cbb6191a6f1d7',
             /*
               role and aria-modal must be used on the
               same element. They must also be set inside the
               shadow DOM otherwise ion-button will not be highlighted
               when using VoiceOver: https://bugs.webkit.org/show_bug.cgi?id=247134
             */
-            role: "dialog" }, inheritedAttributes, { "aria-modal": "true", class: "modal-wrapper ion-overlay-wrapper", part: "content", ref: (el) => (this.wrapperEl = el) }), showHandle && (h("button", { key: '141cdd8f8522331f4b764e2a4d79ec6596b1eb3a', class: "modal-handle",
+            role: "dialog" }, inheritedAttributes, { "aria-modal": "true", class: "modal-wrapper ion-overlay-wrapper", part: "content", ref: (el) => (this.wrapperEl = el) }), showHandle && (h("button", { key: 'd1882835cc049232c0d957e3ba1e79676a07d179', class: "modal-handle",
             // Prevents the handle from receiving keyboard focus when it does not cycle
-            tabIndex: !isHandleCycle ? -1 : 0, "aria-label": "Activate to adjust the size of the dialog overlaying the screen", onClick: isHandleCycle ? this.onHandleClick : undefined, part: "handle", ref: (el) => (this.dragHandleEl = el) })), h("slot", { key: '7de20298b61abee67a16d275c9ebd9a25ce7dd26', onSlotchange: this.onSlotChange }))));
+            tabIndex: !isHandleCycle ? -1 : 0, "aria-label": "Activate to adjust the size of the dialog overlaying the screen", onClick: isHandleCycle ? this.onHandleClick : undefined, part: "handle", ref: (el) => (this.dragHandleEl = el) })), h("slot", { key: '81dc58b09cf7d7022b04cd170f53113604364d5e', onSlotchange: this.onSlotChange }))));
     }
     static get is() { return "ion-modal"; }
     static get encapsulation() { return "shadow"; }

package/dist/collection/components/modal/safe-area-utils.js

@@ -15,6 +15,12 @@ import { raf } from "../../utils/helpers";
 const MODAL_INSET_MIN_WIDTH = 768;
 const MODAL_INSET_MIN_HEIGHT = 600;
 const EDGE_THRESHOLD = 5;
+/**
+ * CSS values for `--width` / `--height` that are treated as fullscreen
+ * (modal touches the corresponding screen edges). Empty string means the
+ * property was not overridden. See `hasCustomModalDimensions()`.
+ */
+const FULLSCREEN_SIZE_VALUES = new Set(['', '100%', '100vw', '100vh', '100dvw', '100dvh', '100svw', '100svh']);
 /**
  * Cache for resolved root safe-area-top value, invalidated once per frame.
  */
@@ -63,6 +69,22 @@ export const getRootSafeAreaTop = () => {
     }
     return value;
 };
+/**
+ * True when the modal host declares BOTH a non-fullscreen `--width` AND a
+ * non-fullscreen `--height` (i.e. a centered-dialog-like modal that doesn't
+ * touch any screen edge).
+ *
+ * The conservative "both axes" check avoids mis-zeroing safe-area for
+ * partial-custom modals where the modal still touches top/bottom edges
+ * (e.g. only `--width` overridden). Partial cases fall through to the
+ * existing position-based post-animation correction.
+ */
+export const hasCustomModalDimensions = (hostEl) => {
+    const styles = getComputedStyle(hostEl);
+    const width = styles.getPropertyValue('--width').trim();
+    const height = styles.getPropertyValue('--height').trim();
+    return !FULLSCREEN_SIZE_VALUES.has(width) && !FULLSCREEN_SIZE_VALUES.has(height);
+};
 /**
  * Returns the initial safe-area configuration based on modal type.
  * This is called before animation starts and uses configuration-based prediction.
@@ -97,8 +119,11 @@ export const getInitialSafeAreaConfig = (context) => {
     }
     // On viewports that meet the centered dialog media query breakpoints,
     // regular modals render as centered dialogs (not fullscreen), so they
-    // don't touch any screen edges and don't need safe-area insets.
-    if (isCenteredDialogViewport()) {
+    // don't touch any screen edges and don't need safe-area insets. Also
+    // applies to phone viewports when the modal declares custom --width and
+    // --height; these don't touch screen edges either, so the initial
+    // prediction must be zero to avoid a post-animation correction flash.
+    if (isCenteredDialogViewport() || context.hasCustomDimensions) {
         return {
             top: '0px',
             bottom: '0px',

package/dist/docs.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-04-27T06:57:23",
+  "timestamp": "2026-04-28T06:58:48",
   "compiler": {
     "name": "@stencil/core",
     "version": "4.43.0",

package/dist/esm/ion-app_8.entry.js

@@ -157,7 +157,7 @@ Buttons.style = {
     md: buttonsMdCss()
 };
 
-const contentCss = () => `:host{--background:var(--ion-background-color, #fff);--color:var(--ion-text-color, #000);--padding-top:0px;--padding-bottom:0px;--padding-start:0px;--padding-end:0px;--keyboard-offset:0px;--offset-top:0px;--offset-bottom:0px;--overflow:auto;display:block;position:relative;-ms-flex:1;flex:1;width:100%;height:100%;margin:0 !important;padding:0 !important;font-family:var(--ion-font-family, inherit);contain:size style}:host(.ion-color) .inner-scroll{background:var(--ion-color-base);color:var(--ion-color-contrast)}#background-content{left:0px;right:0px;top:calc(var(--offset-top) * -1);bottom:calc(var(--offset-bottom) * -1);position:absolute;background:var(--background)}.inner-scroll{left:0px;right:0px;top:calc(var(--offset-top) * -1);bottom:calc(var(--offset-bottom) * -1);-webkit-padding-start:var(--padding-start);padding-inline-start:var(--padding-start);-webkit-padding-end:var(--padding-end);padding-inline-end:var(--padding-end);padding-top:calc(var(--padding-top) + var(--offset-top));padding-bottom:calc(var(--padding-bottom) + var(--keyboard-offset) + var(--offset-bottom));position:absolute;color:var(--color);-webkit-box-sizing:border-box;box-sizing:border-box;overflow:hidden;-ms-touch-action:pan-x pan-y pinch-zoom;touch-action:pan-x pan-y pinch-zoom}.scroll-y,.scroll-x{-webkit-overflow-scrolling:touch;z-index:0;will-change:scroll-position}.scroll-y{overflow-y:var(--overflow);overscroll-behavior-y:contain}.scroll-x{overflow-x:var(--overflow);overscroll-behavior-x:contain}.overscroll::before,.overscroll::after{position:absolute;width:1px;height:1px;content:""}.overscroll::before{bottom:-1px}.overscroll::after{top:-1px}:host(.content-sizing){display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column;min-height:0;contain:none}:host(.content-sizing) .inner-scroll{position:relative;top:0;bottom:0;margin-top:calc(var(--offset-top) * -1);margin-bottom:calc(var(--offset-bottom) * -1)}.transition-effect{display:none;position:absolute;width:100%;height:100vh;opacity:0;pointer-events:none}:host(.content-ltr) .transition-effect{left:-100%;}:host(.content-rtl) .transition-effect{right:-100%;}.transition-cover{position:absolute;right:0;width:100%;height:100%;background:black;opacity:0.1}.transition-shadow{display:block;position:absolute;width:100%;height:100%;-webkit-box-shadow:inset -9px 0 9px 0 rgba(0, 0, 100, 0.03);box-shadow:inset -9px 0 9px 0 rgba(0, 0, 100, 0.03)}:host(.content-ltr) .transition-shadow{right:0;}:host(.content-rtl) .transition-shadow{left:0;-webkit-transform:scaleX(-1);transform:scaleX(-1)}::slotted([slot=fixed]){position:absolute;-webkit-transform:translateZ(0);transform:translateZ(0)}`;
+const contentCss = () => `:host{--background:var(--ion-background-color, #fff);--color:var(--ion-text-color, #000);--padding-top:0px;--padding-bottom:0px;--padding-start:0px;--padding-end:0px;--keyboard-offset:0px;--offset-top:0px;--offset-bottom:0px;--overflow:auto;display:block;position:relative;-ms-flex:1;flex:1;width:100%;height:100%;margin:0 !important;padding:0 !important;font-family:var(--ion-font-family, inherit);contain:size style}:host(.ion-color) .inner-scroll{background:var(--ion-color-base);color:var(--ion-color-contrast)}#background-content{left:0px;right:0px;top:calc(var(--offset-top) * -1);bottom:calc(var(--offset-bottom) * -1);position:absolute;background:var(--background)}.inner-scroll{left:0px;right:0px;top:calc(var(--offset-top) * -1);bottom:calc(var(--offset-bottom) * -1);-webkit-padding-start:var(--padding-start);padding-inline-start:var(--padding-start);-webkit-padding-end:var(--padding-end);padding-inline-end:var(--padding-end);padding-top:calc(var(--padding-top) + var(--offset-top));padding-bottom:calc(var(--padding-bottom) + var(--keyboard-offset) + var(--offset-bottom) + var(--ion-content-safe-area-padding-bottom, 0px));position:absolute;color:var(--color);-webkit-box-sizing:border-box;box-sizing:border-box;overflow:hidden;-ms-touch-action:pan-x pan-y pinch-zoom;touch-action:pan-x pan-y pinch-zoom}.scroll-y,.scroll-x{-webkit-overflow-scrolling:touch;z-index:0;will-change:scroll-position}.scroll-y{overflow-y:var(--overflow);overscroll-behavior-y:contain}.scroll-x{overflow-x:var(--overflow);overscroll-behavior-x:contain}.overscroll::before,.overscroll::after{position:absolute;width:1px;height:1px;content:""}.overscroll::before{bottom:-1px}.overscroll::after{top:-1px}:host(.content-sizing){display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column;min-height:0;contain:none}:host(.content-sizing) .inner-scroll{position:relative;top:0;bottom:0;margin-top:calc(var(--offset-top) * -1);margin-bottom:calc(var(--offset-bottom) * -1)}.transition-effect{display:none;position:absolute;width:100%;height:100vh;opacity:0;pointer-events:none}:host(.content-ltr) .transition-effect{left:-100%;}:host(.content-rtl) .transition-effect{right:-100%;}.transition-cover{position:absolute;right:0;width:100%;height:100%;background:black;opacity:0.1}.transition-shadow{display:block;position:absolute;width:100%;height:100%;-webkit-box-shadow:inset -9px 0 9px 0 rgba(0, 0, 100, 0.03);box-shadow:inset -9px 0 9px 0 rgba(0, 0, 100, 0.03)}:host(.content-ltr) .transition-shadow{right:0;}:host(.content-rtl) .transition-shadow{left:0;-webkit-transform:scaleX(-1);transform:scaleX(-1)}::slotted([slot=fixed]){position:absolute;-webkit-transform:translateZ(0);transform:translateZ(0)}`;
 
 const Content = class {
     constructor(hostRef) {