fix(modal): prevent safe-area flash for custom-dimension modals on phone viewports

Author: ShaneK

core/src/components/content/content.scss

@@ -28,8 +28,6 @@
   --keyboard-offset: 0px;
   --offset-top: 0px;
   --offset-bottom: 0px;
-  // Internal: set by modal applyFullscreenSafeArea() for modals without footer. Not a public API.
-  --ion-content-safe-area-padding-bottom: 0px;
   --overflow: auto;
 
   display: block;
@@ -64,6 +62,12 @@
   background: var(--background);
 }
 
+/**
+ * --ion-content-safe-area-padding-bottom is an internal property set by
+ * modal.tsx for fullscreen modals without an ion-footer. This decouples
+ * safe-area-bottom scroll padding from --padding-bottom (which is a
+ * public property consumers may override).
+ */
 .inner-scroll {
   @include position(calc(var(--offset-top) * -1), 0px,calc(var(--offset-bottom) * -1), 0px);
   @include padding(calc(var(--padding-top) + var(--offset-top)), var(--padding-end), calc(var(--padding-bottom) + var(--keyboard-offset) + var(--offset-bottom) + var(--ion-content-safe-area-padding-bottom, 0px)), var(--padding-start));

core/src/components/modal/modal.tsx

@@ -50,6 +50,7 @@ import {
   applySafeAreaOverrides,
   clearSafeAreaOverrides,
   getRootSafeAreaTop,
+  hasCustomModalDimensions,
   type ModalSafeAreaContext,
 } from './safe-area-utils';
 import { setCardStatusBarDark, setCardStatusBarDefault } from './utils';
@@ -312,11 +313,8 @@ export class Modal implements ComponentInterface, OverlayInterface {
         this.updateSafeAreaOverrides();
 
         // Re-evaluate fullscreen safe-area padding: clear first, then re-apply.
-        // Single findContentAndFooter() call avoids redundant DOM traversal.
         const { contentEl, hasFooter } = this.findContentAndFooter();
-        if (contentEl) {
-          contentEl.style.removeProperty('--ion-content-safe-area-padding-bottom');
-        }
+        this.clearContentSafeAreaPadding(contentEl);
         this.applyFullscreenSafeAreaTo(contentEl, hasFooter);
       }
     }, 50); // Debounce to avoid excessive calls during active resizing
@@ -1430,6 +1428,11 @@ export class Modal implements ComponentInterface, OverlayInterface {
 
   /**
    * 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.
    */
   private getSafeAreaContext(): ModalSafeAreaContext {
     return {
@@ -1452,7 +1455,10 @@ export class Modal implements ComponentInterface, OverlayInterface {
    * sheets to prevent header content from getting double-offset padding).
    */
   private setInitialSafeAreaOverrides(): void {
-    const context = this.getSafeAreaContext();
+    const context: ModalSafeAreaContext = {
+      ...this.getSafeAreaContext(),
+      hasCustomDimensions: hasCustomModalDimensions(this.el),
+    };
     const safeAreaConfig = getInitialSafeAreaConfig(context);
     applySafeAreaOverrides(this.el, safeAreaConfig);
 
@@ -1526,14 +1532,13 @@ export class Modal implements ComponentInterface, OverlayInterface {
   }
 
   /**
-   * Clears --ion-content-safe-area-padding-bottom from ion-content inside
-   * this modal.
+   * 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.
    */
-  private clearContentSafeAreaPadding(): void {
-    const { contentEl } = this.findContentAndFooter();
-    if (contentEl) {
-      contentEl.style.removeProperty('--ion-content-safe-area-padding-bottom');
-    }
+  private clearContentSafeAreaPadding(contentEl: HTMLElement | null): void {
+    if (!contentEl) return;
+    contentEl.style.removeProperty('--ion-content-safe-area-padding-bottom');
   }
 
   /**
@@ -1553,7 +1558,6 @@ export class Modal implements ComponentInterface, OverlayInterface {
     for (const child of Array.from(this.el.children)) {
       if (child.tagName === 'ION-CONTENT') contentEl = child as HTMLElement;
       if (child.tagName === 'ION-FOOTER') hasFooter = true;
-      // Only search grandchildren for content if we haven't found one yet
       for (const grandchild of Array.from(child.children)) {
         if (grandchild.tagName === 'ION-CONTENT' && !contentEl) contentEl = grandchild as HTMLElement;
         if (grandchild.tagName === 'ION-FOOTER') hasFooter = true;
@@ -1571,14 +1575,8 @@ export class Modal implements ComponentInterface, OverlayInterface {
     // Remove internal sheet offset property
     this.el.style.removeProperty('--ion-modal-offset-top');
 
-    // Remove legacy wrapper styles (kept for safety in case they were
-    // set before a live update applied this fix)
-    if (this.wrapperEl) {
-      this.wrapperEl.style.removeProperty('height');
-      this.wrapperEl.style.removeProperty('padding-bottom');
-    }
-
-    this.clearContentSafeAreaPadding();
+    const { contentEl } = this.findContentAndFooter();
+    this.clearContentSafeAreaPadding(contentEl);
   }
 
   render() {

core/src/components/modal/safe-area-utils.ts

@@ -23,6 +23,11 @@ export interface ModalSafeAreaContext {
   presentingElement?: HTMLElement;
   breakpoints?: number[];
   currentBreakpoint?: number;
+  /**
+   * Only consulted by `getInitialSafeAreaConfig()`. Callers that only use the
+   * context for non-initial paths can omit this. See `hasCustomModalDimensions()`.
+   */
+  hasCustomDimensions?: boolean;
 }
 
 /**
@@ -38,6 +43,13 @@ 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.
  */
@@ -92,6 +104,23 @@ export const getRootSafeAreaTop = (): number => {
   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: HTMLElement): boolean => {
+  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.
@@ -129,8 +158,11 @@ export const getInitialSafeAreaConfig = (context: ModalSafeAreaContext): SafeAre
 
   // 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',

core/src/components/modal/test/safe-area/modal.e2e.ts

@@ -322,6 +322,35 @@ configs({ modes: ['ios', 'md'], directions: ['ltr'] }).forEach(({ title, config
       expect(safeAreaBottom).toBe('0px');
     });
 
+    test('centered dialog with custom dimensions on phone should zero safe-area from initial prediction', async ({
+      page,
+    }, testInfo) => {
+      testInfo.annotations.push({
+        type: 'issue',
+        description: 'https://github.com/ionic-team/ionic-framework/issues/31015',
+      });
+
+      // Stay on phone viewport. This is the path where the centered-dialog
+      // media query does NOT match but the modal still doesn't touch screen
+      // edges because cssClass sets --width/--height. Without the initial
+      // prediction catching this, safe-area flashes inherited values and
+      // then snaps to 0px after animation.
+      const ionModalWillPresent = await page.spyOnEvent('ionModalWillPresent');
+      await page.click('#centered-dialog');
+      await ionModalWillPresent.next();
+
+      // Read inline style IMMEDIATELY after will-present fires, before the
+      // animation finishes. This captures the initial prediction value.
+      const modal = page.locator('ion-modal');
+      const initial = await modal.evaluate((el: HTMLIonModalElement) => ({
+        top: el.style.getPropertyValue('--ion-safe-area-top'),
+        bottom: el.style.getPropertyValue('--ion-safe-area-bottom'),
+      }));
+
+      expect(initial.top).toBe('0px');
+      expect(initial.bottom).toBe('0px');
+    });
+
     test('safe-area overrides should be cleared on dismiss', async ({ page }, testInfo) => {
       testInfo.annotations.push({
         type: 'issue',