ionic-team · HappyKnuckles · Dec 11, 2025 · Dec 12, 2025 · Dec 23, 2025 · May 13, 2026
@@ -38,6 +38,8 @@ import type { ScrollBaseDetail, ScrollDetail } from './content-interface';
 })
 export class Content implements ComponentInterface {
   private watchDog: ReturnType<typeof setInterval> | null = null;
+  private mutationObserver: MutationObserver | null = null;
+  private resizeObserver: ResizeObserver | null = null;
   private isScrolling = false;
   private lastScroll = 0;
   private queued = false;
@@ -47,6 +49,7 @@ export class Content implements ComponentInterface {
   private backgroundContentEl?: HTMLElement;
   private isMainContent = true;
   private resizeTimeout: ReturnType<typeof setTimeout> | null = null;
+  private observerResizeRaf: ReturnType<typeof requestAnimationFrame> | null = null;
   private fullscreenResizeObserver?: ResizeObserver;
   private inheritedAttributes: Attributes = {};
 
@@ -187,6 +190,7 @@ export class Content implements ComponentInterface {
         closestTabs.addEventListener('ionTabBarLoaded', this.tabsLoadCallback);
       }
     }
+    this.connectObservers();
 
     // Re-observe on reattach, since componentDidLoad only fires once.
     this.setupFullscreenResizeObserver();
@@ -199,6 +203,7 @@ export class Content implements ComponentInterface {
 
   disconnectedCallback() {
     this.onScrollEnd();
+    this.disconnectObservers();
 
     if (hasLazyBuild(this.el)) {
       /**
@@ -495,6 +500,95 @@ export class Content implements ComponentInterface {
     return promise;
   }
 
+  /**
+   * We need to observe the parent element to detect when
+   * <ion-header> or <ion-footer> elements are added/removed
+   * or resized. This ensures the content offset is recalculated
+   * dynamically.
+   */
+  private connectObservers() {
+    if (!Build.isBrowser) {
+      return;
+    }
+
+    const parent = this.el.parentElement;
+    if (!parent) {
+      return;
+    }
+
+    if ('ResizeObserver' in window) {
+      this.resizeObserver = new ResizeObserver(() => {
+        if (this.observerResizeRaf !== null) {
+          cancelAnimationFrame(this.observerResizeRaf);
+        }
+
+        this.observerResizeRaf = requestAnimationFrame(() => {
+          this.observerResizeRaf = null;
+          this.resize();
+        });
+      });
+    }
+
+    if ('MutationObserver' in window) {
+      this.mutationObserver = new MutationObserver((mutations) => {
+        let shouldUpdate = false;
+
+        for (const mutation of mutations) {
+          if (mutation.type === 'childList') {
+            mutation.addedNodes.forEach((node: Node) => {
+              if (node instanceof HTMLElement && (node.tagName === 'ION-HEADER' || node.tagName === 'ION-FOOTER')) {
+                shouldUpdate = true;
+              }
+            });
+
+            mutation.removedNodes.forEach((node: Node) => {
+              if (node instanceof HTMLElement && (node.tagName === 'ION-HEADER' || node.tagName === 'ION-FOOTER')) {
+                shouldUpdate = true;
+              }
+            });
+          }
+        }
+
+        if (shouldUpdate) {
+          this.refreshResizeObserver();
+          this.resize();
+        }
+      });
+
+      this.mutationObserver.observe(parent, { childList: true });
+    }
+
+    this.refreshResizeObserver();
+  }
+
+  private disconnectObservers() {
+    if (this.observerResizeRaf !== null) {
+      cancelAnimationFrame(this.observerResizeRaf);
+      this.observerResizeRaf = null;
+    }
+    if (this.mutationObserver) {
+      this.mutationObserver.disconnect();
+      this.mutationObserver = null;
+    }
+    if (this.resizeObserver) {
+      this.resizeObserver.disconnect();
+      this.resizeObserver = null;
+    }
+  }
+
+  private refreshResizeObserver() {
+    if (!this.resizeObserver || !this.el.parentElement) {
+      return;
+    }
+
+    this.resizeObserver.disconnect();
+
+    const targets = this.el.parentElement.querySelectorAll(':scope > ion-header, :scope > ion-footer');
+
+    const observer = this.resizeObserver;
+    targets.forEach((target) => observer.observe(target));
+  }
+
   private onScrollStart() {
     this.isScrolling = true;
     this.ionScrollStart.emit({

@@ -0,0 +1,42 @@
+import { expect } from '@playwright/test';
+import { test, configs } from '@utils/test/playwright';
+
+configs().forEach(({ title, screenshot, config }) => {
+  test.describe(title('content: auto offset'), () => {
+    test('should not have visual regressions', async ({ page }) => {
+      await page.goto(`/src/components/content/test/auto-offset`, config);
+      await page.setIonViewport();
+      await expect(page).toHaveScreenshot(screenshot(`content-auto-offset-initial`));
+    });
+
+    test('should update offsets when header height changes', async ({ page }) => {
+      await page.goto(`/src/components/content/test/auto-offset`, config);
+      await page.setIonViewport();
+
+      const content = page.locator('ion-content');
+      const before = await content.evaluate((el: HTMLElement) => getComputedStyle(el).getPropertyValue('--offset-top'));
+
+      await page.click('#expand-header-btn');
+
+      await expect(content).not.toHaveCSS('--offset-top', before);
+
+      await expect(page).toHaveScreenshot(screenshot(`content-auto-offset-header-updated`));
+    });
+
+    test('should update offsets when footer height changes', async ({ page }) => {
+      await page.goto(`/src/components/content/test/auto-offset`, config);
+      await page.setIonViewport();
+
+      const content = page.locator('ion-content');
+      const before = await content.evaluate((el: HTMLElement) =>
+        getComputedStyle(el).getPropertyValue('--offset-bottom')
+      );
+
+      await page.click('#expand-footer-btn');
+
+      await expect(content).not.toHaveCSS('--offset-bottom', before);
+
+      await expect(page).toHaveScreenshot(screenshot(`content-auto-offset-footer-updated`));
+    });
+  });
+});
@@ -0,0 +1,58 @@
+<!DOCTYPE html>
+<html lang="en" dir="ltr">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Content - Auto Offset</title>
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no"
+    />
+    <link href="../../../../../css/ionic.bundle.css" rel="stylesheet" />
+    <link href="../../../../../scripts/testing/styles.css" rel="stylesheet" />
+    <script src="../../../../../scripts/testing/scripts.js"></script>
+    <script nomodule src="../../../../../dist/ionic/ionic.js"></script>
+    <script type="module" src="../../../../../dist/ionic/ionic.esm.js"></script>
+  </head>
+
+  <body>
+    <ion-app mode="ios">
+      <ion-header translucent>
+        <ion-toolbar>
+          <ion-title>Auto Offset Test</ion-title>
+        </ion-toolbar>
+        <ion-toolbar id="extra-header-content" style="display: none">
+          <ion-searchbar label="dynamic"></ion-searchbar>
+        </ion-toolbar>
+      </ion-header>
+
+      <ion-content fullscreen style="--background: blue">
+        <button id="expand-header-btn">Expand Header</button>
+        <br /><br />
+        <button id="expand-footer-btn">Expand Footer</button>
+      </ion-content>
+
+      <ion-footer translucent>
+        <ion-toolbar id="extra-footer-content" style="display: none">
+          <div class="ion-padding">Expanded Footer Area</div>
+        </ion-toolbar>
+        <ion-toolbar>
+          <ion-title>Footer</ion-title>
+        </ion-toolbar>
+      </ion-footer>
+    </ion-app>
+    <script>
+      const headerBtn = document.getElementById('expand-header-btn');
+      const footerBtn = document.getElementById('expand-footer-btn');
+      const extraHeaderToolBar = document.getElementById('extra-header-content');
+      const extraFooterToolbar = document.getElementById('extra-footer-content');
+
+      headerBtn.addEventListener('click', () => {
+        extraHeaderToolBar.style.display = 'flex';
+      });
+
+      footerBtn.addEventListener('click', () => {
+        extraFooterToolbar.style.display = 'flex';
+      });
+    </script>
+  </body>
+</html>