ionic-team · rdlabo · Jul 22, 2025 · Jul 22, 2025 · Jul 22, 2025 · Jul 22, 2025
@@ -24,3 +24,4 @@ yarn-debug.log*
 yarn-error.log*
 
 static/**/node_modules/
+.idea
@@ -13,6 +13,7 @@ Udemy
 Vetur
 Wistia
 WCAG
+CDK
 
 actionsheet
 fabs
@@ -85,6 +86,3 @@ webnative
 
 browserslistrc
 ionicframework
-tappable
-Overscroll
-expressjs
@@ -0,0 +1,213 @@
+---
+title: Overlay Components
+sidebar_label: Overlays
+---
+
+<head>
+  <title>Angular Overlay Components: Modals, Popovers with Custom Injectors</title>
+  <meta
+    name="description"
+    content="Learn how to use overlay components like modals and popovers in Ionic Angular, including passing custom injectors for dependency injection."
+  />
+</head>
+
+Ionic provides overlay components such as modals and popovers that display content on top of your application. In Angular, these overlays can be created using controllers like `ModalController` and `PopoverController`.
+
+## Creating Overlays
+
+Overlays can be created programmatically using their respective controllers:
+
+```typescript
+import { Component } from '@angular/core';
+import { ModalController } from '@ionic/angular/standalone';
+import { MyModalComponent } from './my-modal.component';
+
+@Component({
+  selector: 'app-home',
+  templateUrl: './home.component.html',
+})
+export class HomeComponent {
+  constructor(private modalController: ModalController) {}
+
+  async openModal() {
+    const modal = await this.modalController.create({
+      component: MyModalComponent,
+      componentProps: {
+        title: 'My Modal',
+      },
+    });
+    await modal.present();
+  }
+}
+```
+
+## Custom Injectors
+
+By default, overlay components use the root injector for dependency injection. This means that services or tokens provided at the route level or within a specific component tree are not accessible inside the overlay.
+
+The `injector` option allows you to pass a custom Angular `Injector` when creating a modal or popover. This enables overlay components to access services and tokens that are not available in the root injector.
+
+### Use Cases
+
+Custom injectors are useful when you need to:
+
+- Access route-scoped services from within an overlay
+- Use Angular CDK's `Dir` directive for bidirectional text support
+- Access any providers that are not registered at the root level
+
+### Usage
+
+To use a custom injector, pass it to the `create()` method:
+
+```typescript
+import { Component, Injector } from '@angular/core';
+import { ModalController } from '@ionic/angular/standalone';
+import { MyModalComponent } from './my-modal.component';
+import { MyRouteService } from './my-route.service';
+
+@Component({
+  selector: 'app-feature',
+  templateUrl: './feature.component.html',
+  providers: [MyRouteService], // Service provided at route level
+})
+export class FeatureComponent {
+  constructor(private modalController: ModalController, private injector: Injector) {}
+
+  async openModal() {
+    const modal = await this.modalController.create({
+      component: MyModalComponent,
+      injector: this.injector, // Pass the component's injector
+    });
+    await modal.present();
+  }
+}
+```
+
+The modal component can now inject `MyRouteService`:
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { MyRouteService } from '../my-route.service';
+
+@Component({
+  selector: 'app-my-modal',
+  templateUrl: './my-modal.component.html',
+})
+export class MyModalComponent {
+  private myRouteService = inject(MyRouteService);
+}
+```
+
+### Creating a Custom Injector
+
+You can also create a custom injector with specific providers:
+
+```typescript
+import { Component, Injector } from '@angular/core';
+import { ModalController } from '@ionic/angular/standalone';
+import { MyModalComponent } from './my-modal.component';
+import { MyService } from './my.service';
+
+@Component({
+  selector: 'app-feature',
+  templateUrl: './feature.component.html',
+})
+export class FeatureComponent {
+  constructor(private modalController: ModalController, private injector: Injector) {}
+
+  async openModal() {
+    const myService = new MyService();
+    myService.configure({ someOption: true });
+
+    const customInjector = Injector.create({
+      providers: [{ provide: MyService, useValue: myService }],
+      parent: this.injector,
+    });
+
+    const modal = await this.modalController.create({
+      component: MyModalComponent,
+      injector: customInjector,
+    });
+    await modal.present();
+  }
+}
+```
+
+### Using with Angular CDK Directionality
+
+A common use case is providing the Angular CDK `Dir` directive to overlays for bidirectional text support:
+
+```typescript
+import { Component, Injector } from '@angular/core';
+import { Dir } from '@angular/cdk/bidi';
+import { ModalController } from '@ionic/angular/standalone';
+import { MyModalComponent } from './my-modal.component';
+
+@Component({
+  selector: 'app-feature',
+  templateUrl: './feature.component.html',
+})
+export class FeatureComponent {
+  constructor(private modalController: ModalController, private injector: Injector) {}
+
+  async openModal() {
+    const modal = await this.modalController.create({
+      component: MyModalComponent,
+      injector: this.injector, // Includes Dir from component tree
+    });
+    await modal.present();
+  }
+}
+```
+
+### Popover Controller
+
+The `PopoverController` supports the same `injector` option:
+
+```typescript
+import { Component, Injector } from '@angular/core';
+import { PopoverController } from '@ionic/angular/standalone';
+import { MyPopoverComponent } from './my-popover.component';
+
+@Component({
+  selector: 'app-feature',
+  templateUrl: './feature.component.html',
+})
+export class FeatureComponent {
+  constructor(private popoverController: PopoverController, private injector: Injector) {}
+
+  async openPopover(event: Event) {
+    const popover = await this.popoverController.create({
+      component: MyPopoverComponent,
+      event: event,
+      injector: this.injector,
+    });
+    await popover.present();
+  }
+}
+```
+
+## Angular Options Types
+
+Ionic Angular exports its own `ModalOptions` and `PopoverOptions` types that extend the core options with Angular-specific properties like `injector`:
+
+- `ModalOptions` - Extends core `ModalOptions` with the `injector` property
+- `PopoverOptions` - Extends core `PopoverOptions` with the `injector` property
+
+These types are exported from `@ionic/angular` and `@ionic/angular/standalone`:
+
+```typescript
+import type { ModalOptions, PopoverOptions } from '@ionic/angular/standalone';
+```
+
+## Docs for Overlays in Ionic
+
+For full docs and to see usage examples, visit the docs page for each of the overlays in Ionic:
+
+- [Action Sheet](https://ionicframework.com/docs/api/action-sheet)
+- [Alert](https://ionicframework.com/docs/api/alert)
+- [Loading](https://ionicframework.com/docs/api/loading)
+- [Modal](https://ionicframework.com/docs/api/modal)
+- [Picker](https://ionicframework.com/docs/api/picker)
+- [Popover](https://ionicframework.com/docs/api/popover)
+- [Toast](https://ionicframework.com/docs/api/toast)
@@ -41,7 +41,9 @@ import ShowAdjacentDays from '@site/static/usage/v8/datetime/show-adjacent-days/
 import MultipleDateSelection from '@site/static/usage/v8/datetime/multiple/index.md';
 
 import GlobalTheming from '@site/static/usage/v8/datetime/styling/global-theming/index.md';
+import CalendarHeaderStyling from '@site/static/usage/v8/datetime/styling/calendar-header/index.md';
 import CalendarDaysStyling from '@site/static/usage/v8/datetime/styling/calendar-days/index.md';
+import DatetimeHeaderStyling from '@site/static/usage/v8/datetime/styling/datetime-header/index.md';
 import WheelStyling from '@site/static/usage/v8/datetime/styling/wheel-styling/index.md';
 
 <head>
@@ -352,6 +354,24 @@ Ionicの強力なテーマシステムを使用すると、特定のテーマに
 
 <GlobalTheming />
 
+### Datetime Header
+
+The datetime header manages the content for the `title` slot and the selected date.
+
+:::note
+The selected date will not render if `preferWheel` is set to `true`.
+:::
+
+<DatetimeHeaderStyling />
+
+### Calender Header
+
+The calendar header manages the date navigation controls (month/year picker and prev/next buttons) and the days of the week when using a grid style layout.
+
+The header can be styled using CSS shadow parts.
+
+<CalendarHeaderStyling />
+
 ### Calendar Days
 
 The calendar days in a grid-style `ion-datetime` can be styled using CSS shadow parts.

@@ -212,6 +212,26 @@ import CustomDialogs from '@site/static/usage/v8/modal/custom-dialogs/index.md';
 * `ion-content` は、フルページモダル、カード、シートで使用することを意図しています。カスタムダイアログのサイズが動的であったり、不明であったりする場合は、 `ion-content` を使用するべきではありません。
 * カスタムダイアログを作成することは、デフォルトのモーダルエクスペリエンスから逃れる方法を提供します。そのため、カスタムダイアログは、カードやシートのモーダルでは使用しないでください。
 
+## Event Handling
+
+### Using `ionDragStart` and `ionDragEnd`
+
+The `ionDragStart` event is emitted as soon as the user begins a dragging gesture on the modal. This event fires at the moment the user initiates contact with the handle or modal surface, before any actual displacement occurs. It is particularly useful for preparing the interface for a transition, such as hiding certain interactive elements (like headers or buttons) to ensure a smooth dragging experience.
+
+The `ionDragEnd` event is emitted when the user completes the dragging gesture by releasing the modal. Like the move event, it includes the final [`ModalDragEventDetail`](#modaldrageventdetail) object. This event is commonly used to finalize state changes once the modal has come to a rest.
+
+import DragStartEndEvents from '@site/static/usage/v8/modal/drag-start-end-events/index.md';
+
+<DragStartEndEvents />
+
+### Using `ionDragMove`
+
+The `ionDragMove` event is emitted continuously while the user is actively dragging the modal. This event provides a [`ModalDragEventDetail`](#modaldrageventdetail) object containing real-time data, essential for creating highly responsive UI updates that react instantly to the user's touch. For example, the `progress` value can be used to dynamically darken a header's opacity as the modal is dragged upward.
+
+import DragMoveEvent from '@site/static/usage/v8/modal/drag-move-event/index.md';
+
+<DragMoveEvent />
+
 ## Interfaces
 
 ### ModalOptions
@@ -253,7 +273,60 @@ interface ModalCustomEvent extends CustomEvent {
 }
 ```
 
-## アクセシビリティ
+### ModalDragEventDetail
+
+When using the `ionDragMove` and `ionDragEnd` events, the event detail contains the following properties:
+
+```typescript
+interface ModalDragEventDetail {
+  /**
+   * The current Y position of the modal.
+   *
+   * This can be used to determine how far the modal has been dragged.
+   */
+  currentY: number;
+  /**
+   * The change in Y position since the gesture started.
+   *
+   * This can be used to determine the direction of the drag.
+   */
+  deltaY: number;
+  /**
+   * The velocity of the drag in the Y direction.
+   *
+   * This can be used to determine how fast the modal is being dragged.
+   */
+  velocityY: number;
+  /**
+   * A number between 0 and 1.
+   *
+   * In a sheet modal, progress represents the relative position between
+   * the lowest and highest defined breakpoints.
+   *
+   * In a card modal, it measures the relative position between the
+   * bottom of the screen and the top of the modal when it is fully
+   * open.
+   *
+   * This can be used to style content based on how far the modal has
+   * been dragged.
+   */
+  progress: number;
+  /**
+   * If the modal is a sheet modal, this will be the breakpoint that
+   * the modal will snap to if the user lets go of the modal at the
+   * current moment.
+   *
+   * If it's a card modal, this property will not be included in the
+   * event payload.
+   *
+   * This can be used to style content based on where the modal will
+   * snap to upon release.
+   */
+  snapBreakpoint?: number;
+}
+```
+
+## Accessibility
 
 ### Keyboard Interactions
 

@@ -297,6 +297,37 @@ Each [Picker Column](./picker-column) can be navigated using the keyboard when f
 | <kbd>Home</kbd>      | Scroll to the first option.          |
 | <kbd>End</kbd>       | Scroll to the last option.           |
 
+## Accessibility
+
+### Screen Readers
+
+Pickerは、各[Picker Column](./picker-column)に[`slider` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role)を実装することで、スクリーンリーダーを使用したナビゲーションをサポートします。以下のジェスチャーを使用してPickerをナビゲートできます。
+
+| Gesture | Function |
+| - | - |
+| Swipe Left | Move focus to the previous Picker Column. |
+| Swipe Right | Move focus to the next Picker Column. |
+| Swipe Up | Select the next option in the Picker Column. |
+| Swipe Down | Select the previous option in the Picker Column. |
+| Double Tap and Slide Up/Down | Adjust the selected option in the Picker Column. Can be used as an alternative to swiping up and down. |
+
+:::caution
+The Swipe Up and Swipe Down gestures rely on the correct key events being synthesized as noted on the [`slider` documentation](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role). [Chromium-based browsers do not synthesize keyboard events correctly](https://issues.chromium.org/issues/40816094), but the "Double Tap and Slide Up/Down" gesture can be used as an alternative until this has been implemented in Chromium-based browsers.
+:::
+
+### Keyboard Interactions
+
+Each [Picker Column](./picker-column) can be navigated using the keyboard when focused.
+
+| Key                  | Description                          |
+| -------------------- | ------------------------------------ |
+| <kbd>ArrowUp</kbd>   | Scroll to the previous option.       |
+| <kbd>ArrowDown</kbd> | Scroll to the next option.           |
+| <kbd>PageUp</kbd>    | Scroll up by more than one option.   |
+| <kbd>PageDown</kbd>  | Scroll down by more than one option. |
+| <kbd>Home</kbd>      | Scroll to the first option.          |
+| <kbd>End</kbd>       | Scroll to the last option.           |
+
 ## プロパティ
 <Props />
Original file line number	Diff line number	Diff line change
Expand Up		@@ -24,3 +24,4 @@ yarn-debug.log*
		yarn-error.log*

		static/**/node_modules/
		.idea