|
| 1 | +--- |
| 2 | +title: Overlay Components |
| 3 | +sidebar_label: Overlays |
| 4 | +--- |
| 5 | + |
| 6 | +<head> |
| 7 | + <title>Angular Overlay Components: Modals, Popovers with Custom Injectors</title> |
| 8 | + <meta |
| 9 | + name="description" |
| 10 | + content="Learn how to use overlay components like modals and popovers in Ionic Angular, including passing custom injectors for dependency injection." |
| 11 | + /> |
| 12 | +</head> |
| 13 | + |
| 14 | +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`. |
| 15 | + |
| 16 | +## Creating Overlays |
| 17 | + |
| 18 | +Overlays can be created programmatically using their respective controllers: |
| 19 | + |
| 20 | +```typescript |
| 21 | +import { Component } from '@angular/core'; |
| 22 | +import { ModalController } from '@ionic/angular/standalone'; |
| 23 | +import { MyModalComponent } from './my-modal.component'; |
| 24 | + |
| 25 | +@Component({ |
| 26 | + selector: 'app-home', |
| 27 | + templateUrl: './home.component.html', |
| 28 | +}) |
| 29 | +export class HomeComponent { |
| 30 | + constructor(private modalController: ModalController) {} |
| 31 | + |
| 32 | + async openModal() { |
| 33 | + const modal = await this.modalController.create({ |
| 34 | + component: MyModalComponent, |
| 35 | + componentProps: { |
| 36 | + title: 'My Modal', |
| 37 | + }, |
| 38 | + }); |
| 39 | + await modal.present(); |
| 40 | + } |
| 41 | +} |
| 42 | +``` |
| 43 | + |
| 44 | +## Custom Injectors |
| 45 | + |
| 46 | +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. |
| 47 | + |
| 48 | +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. |
| 49 | + |
| 50 | +### Use Cases |
| 51 | + |
| 52 | +Custom injectors are useful when you need to: |
| 53 | + |
| 54 | +- Access route-scoped services from within an overlay |
| 55 | +- Use Angular CDK's `Dir` directive for bidirectional text support |
| 56 | +- Access any providers that are not registered at the root level |
| 57 | + |
| 58 | +### Usage |
| 59 | + |
| 60 | +To use a custom injector, pass it to the `create()` method: |
| 61 | + |
| 62 | +```typescript |
| 63 | +import { Component, Injector } from '@angular/core'; |
| 64 | +import { ModalController } from '@ionic/angular/standalone'; |
| 65 | +import { MyModalComponent } from './my-modal.component'; |
| 66 | +import { MyRouteService } from './my-route.service'; |
| 67 | + |
| 68 | +@Component({ |
| 69 | + selector: 'app-feature', |
| 70 | + templateUrl: './feature.component.html', |
| 71 | + providers: [MyRouteService], // Service provided at route level |
| 72 | +}) |
| 73 | +export class FeatureComponent { |
| 74 | + constructor(private modalController: ModalController, private injector: Injector) {} |
| 75 | + |
| 76 | + async openModal() { |
| 77 | + const modal = await this.modalController.create({ |
| 78 | + component: MyModalComponent, |
| 79 | + injector: this.injector, // Pass the component's injector |
| 80 | + }); |
| 81 | + await modal.present(); |
| 82 | + } |
| 83 | +} |
| 84 | +``` |
| 85 | + |
| 86 | +The modal component can now inject `MyRouteService`: |
| 87 | + |
| 88 | +```typescript |
| 89 | +import { Component, inject } from '@angular/core'; |
| 90 | +import { MyRouteService } from '../my-route.service'; |
| 91 | + |
| 92 | +@Component({ |
| 93 | + selector: 'app-my-modal', |
| 94 | + templateUrl: './my-modal.component.html', |
| 95 | +}) |
| 96 | +export class MyModalComponent { |
| 97 | + private myRouteService = inject(MyRouteService); |
| 98 | +} |
| 99 | +``` |
| 100 | + |
| 101 | +### Creating a Custom Injector |
| 102 | + |
| 103 | +You can also create a custom injector with specific providers: |
| 104 | + |
| 105 | +```typescript |
| 106 | +import { Component, Injector } from '@angular/core'; |
| 107 | +import { ModalController } from '@ionic/angular/standalone'; |
| 108 | +import { MyModalComponent } from './my-modal.component'; |
| 109 | +import { MyService } from './my.service'; |
| 110 | + |
| 111 | +@Component({ |
| 112 | + selector: 'app-feature', |
| 113 | + templateUrl: './feature.component.html', |
| 114 | +}) |
| 115 | +export class FeatureComponent { |
| 116 | + constructor(private modalController: ModalController, private injector: Injector) {} |
| 117 | + |
| 118 | + async openModal() { |
| 119 | + const myService = new MyService(); |
| 120 | + myService.configure({ someOption: true }); |
| 121 | + |
| 122 | + const customInjector = Injector.create({ |
| 123 | + providers: [{ provide: MyService, useValue: myService }], |
| 124 | + parent: this.injector, |
| 125 | + }); |
| 126 | + |
| 127 | + const modal = await this.modalController.create({ |
| 128 | + component: MyModalComponent, |
| 129 | + injector: customInjector, |
| 130 | + }); |
| 131 | + await modal.present(); |
| 132 | + } |
| 133 | +} |
| 134 | +``` |
| 135 | + |
| 136 | +### Using with Angular CDK Directionality |
| 137 | + |
| 138 | +A common use case is providing the Angular CDK `Dir` directive to overlays for bidirectional text support: |
| 139 | + |
| 140 | +```typescript |
| 141 | +import { Component, Injector } from '@angular/core'; |
| 142 | +import { Dir } from '@angular/cdk/bidi'; |
| 143 | +import { ModalController } from '@ionic/angular/standalone'; |
| 144 | +import { MyModalComponent } from './my-modal.component'; |
| 145 | + |
| 146 | +@Component({ |
| 147 | + selector: 'app-feature', |
| 148 | + templateUrl: './feature.component.html', |
| 149 | +}) |
| 150 | +export class FeatureComponent { |
| 151 | + constructor(private modalController: ModalController, private injector: Injector) {} |
| 152 | + |
| 153 | + async openModal() { |
| 154 | + const modal = await this.modalController.create({ |
| 155 | + component: MyModalComponent, |
| 156 | + injector: this.injector, // Includes Dir from component tree |
| 157 | + }); |
| 158 | + await modal.present(); |
| 159 | + } |
| 160 | +} |
| 161 | +``` |
| 162 | + |
| 163 | +### Popover Controller |
| 164 | + |
| 165 | +The `PopoverController` supports the same `injector` option: |
| 166 | + |
| 167 | +```typescript |
| 168 | +import { Component, Injector } from '@angular/core'; |
| 169 | +import { PopoverController } from '@ionic/angular/standalone'; |
| 170 | +import { MyPopoverComponent } from './my-popover.component'; |
| 171 | + |
| 172 | +@Component({ |
| 173 | + selector: 'app-feature', |
| 174 | + templateUrl: './feature.component.html', |
| 175 | +}) |
| 176 | +export class FeatureComponent { |
| 177 | + constructor(private popoverController: PopoverController, private injector: Injector) {} |
| 178 | + |
| 179 | + async openPopover(event: Event) { |
| 180 | + const popover = await this.popoverController.create({ |
| 181 | + component: MyPopoverComponent, |
| 182 | + event: event, |
| 183 | + injector: this.injector, |
| 184 | + }); |
| 185 | + await popover.present(); |
| 186 | + } |
| 187 | +} |
| 188 | +``` |
| 189 | + |
| 190 | +## Angular Options Types |
| 191 | + |
| 192 | +Ionic Angular exports its own `ModalOptions` and `PopoverOptions` types that extend the core options with Angular-specific properties like `injector`: |
| 193 | + |
| 194 | +- `ModalOptions` - Extends core `ModalOptions` with the `injector` property |
| 195 | +- `PopoverOptions` - Extends core `PopoverOptions` with the `injector` property |
| 196 | + |
| 197 | +These types are exported from `@ionic/angular` and `@ionic/angular/standalone`: |
| 198 | + |
| 199 | +```typescript |
| 200 | +import type { ModalOptions, PopoverOptions } from '@ionic/angular/standalone'; |
| 201 | +``` |
| 202 | + |
| 203 | +## Docs for Overlays in Ionic |
| 204 | + |
| 205 | +For full docs and to see usage examples, visit the docs page for each of the overlays in Ionic: |
| 206 | + |
| 207 | +- [Action Sheet](https://ionicframework.com/docs/api/action-sheet) |
| 208 | +- [Alert](https://ionicframework.com/docs/api/alert) |
| 209 | +- [Loading](https://ionicframework.com/docs/api/loading) |
| 210 | +- [Modal](https://ionicframework.com/docs/api/modal) |
| 211 | +- [Picker](https://ionicframework.com/docs/api/picker) |
| 212 | +- [Popover](https://ionicframework.com/docs/api/popover) |
| 213 | +- [Toast](https://ionicframework.com/docs/api/toast) |
0 commit comments