0
# Overlay Management
1

2
React hooks and components for managing modal dialogs, alerts, toasts, action sheets, and other overlay components with both declarative and imperative APIs.
3

4
## Capabilities
5

6
### Alert Management
7

8
Hook for creating and managing alert dialogs with buttons and input fields.
9

10
```typescript { .api }
11
/**
12
 * Hook for managing alert dialogs.
13
 * Returns functions to present and dismiss alerts.
14
 * @returns [present, dismiss] - Functions to show and hide alerts
15
 */
16
function useIonAlert(): [
17
  {
18
    (message: string, buttons?: AlertButton[]): Promise<void>;
19
    (options: AlertOptions): Promise<void>;
20
  },
21
  () => Promise<void>
22
];
23

24
interface AlertOptions {
25
  /** Alert header text */
26
  header?: string;
27
  /** Alert subheader text */
28
  subHeader?: string;
29
  /** Alert message content */
30
  message?: string;
31
  /** Array of buttons or button configurations */
32
  buttons?: (string | AlertButton)[];
33
  /** Array of input fields */
34
  inputs?: AlertInput[];
35
  /** Custom CSS class */
36
  cssClass?: string;
37
  /** Whether clicking backdrop dismisses alert */
38
  backdropDismiss?: boolean;
39
  /** Whether alert is translucent */
40
  translucent?: boolean;
41
  /** Animation to use when presenting */
42
  enterAnimation?: any;
43
  /** Animation to use when dismissing */
44
  leaveAnimation?: any;
45
}
46

47
interface AlertButton {
48
  /** Button text */
49
  text: string;
50
  /** Button role */
51
  role?: 'cancel' | 'destructive';
52
  /** Custom CSS class */
53
  cssClass?: string;
54
  /** Click handler */
55
  handler?: (value: any) => boolean | void | Promise<boolean | void>;
56
}
57

58
interface AlertInput {
59
  /** Input type */
60
  type?: 'text' | 'email' | 'number' | 'password' | 'search' | 'tel' | 'url' | 'checkbox' | 'radio';
61
  /** Input name */
62
  name?: string;
63
  /** Input placeholder */
64
  placeholder?: string;
65
  /** Input value */
66
  value?: any;
67
  /** Whether input is checked (for checkbox/radio) */
68
  checked?: boolean;
69
  /** Whether input is disabled */
70
  disabled?: boolean;
71
  /** Input id */
72
  id?: string;
73
}
74
```
75

76
### Modal Management
77

78
Hook for creating and managing modal dialogs with React components.
79

80
```typescript { .api }
81
/**
82
 * Hook for managing modal dialogs with React components.
83
 * @param component - React component to render in modal
84
 * @param componentProps - Props to pass to the component
85
 * @returns [present, dismiss] - Functions to show and hide modals
86
 */
87
function useIonModal(
88
  component: ReactComponentOrElement,
89
  componentProps?: any
90
): [
91
  (options?: ModalOptions) => Promise<void>,
92
  () => Promise<void>
93
];
94

95
type ReactComponentOrElement = React.ComponentType<any> | React.ReactElement;
96

97
interface ModalOptions {
98
  /** Whether to show backdrop */
99
  showBackdrop?: boolean;
100
  /** Whether clicking backdrop dismisses modal */
101
  backdropDismiss?: boolean;
102
  /** Custom CSS class */
103
  cssClass?: string;
104
  /** Whether modal can be dismissed by swipe gesture */
105
  canDismiss?: boolean | (() => Promise<boolean>);
106
  /** Breakpoints for sheet-style modals */
107
  breakpoints?: number[];
108
  /** Initial breakpoint for sheet-style modals */
109
  initialBreakpoint?: number;
110
  /** Animation to use when presenting */
111
  enterAnimation?: any;
112
  /** Animation to use when dismissing */
113
  leaveAnimation?: any;
114
  /** Callback when modal will dismiss */
115
  onWillDismiss?: (event: CustomEvent) => void;
116
  /** Callback when modal did dismiss */
117
  onDidDismiss?: (event: CustomEvent) => void;
118
}
119
```
120

121
### Toast Management
122

123
Hook for creating and managing toast notifications.
124

125
```typescript { .api }
126
/**
127
 * Hook for managing toast notifications.
128
 * Returns functions to present and dismiss toasts.
129
 * @returns [present, dismiss] - Functions to show and hide toasts
130
 */
131
function useIonToast(): [
132
  (options: ToastOptions) => Promise<void>,
133
  () => void
134
];
135

136
interface ToastOptions {
137
  /** Toast message text */
138
  message: string;
139
  /** Duration in milliseconds (0 = indefinite) */
140
  duration?: number;
141
  /** Position on screen */
142
  position?: 'top' | 'middle' | 'bottom';
143
  /** Toast color theme */
144
  color?: string;
145
  /** Custom CSS class */
146
  cssClass?: string;
147
  /** Array of action buttons */
148
  buttons?: (string | ToastButton)[];
149
  /** Icon to display */
150
  icon?: any;
151
  /** Whether toast is translucent */
152
  translucent?: boolean;
153
  /** Animation to use when presenting */
154
  enterAnimation?: any;
155
  /** Animation to use when dismissing */
156
  leaveAnimation?: any;
157
}
158

159
interface ToastButton {
160
  /** Button text */
161
  text?: string;
162
  /** Button icon */
163
  icon?: any;
164
  /** Button side */
165
  side?: 'start' | 'end';
166
  /** Button role */
167
  role?: 'cancel';
168
  /** Custom CSS class */
169
  cssClass?: string;
170
  /** Click handler */
171
  handler?: () => boolean | void | Promise<boolean | void>;
172
}
173
```
174

175
### Action Sheet Management
176

177
Hook for creating and managing action sheet overlays.
178

179
```typescript { .api }
180
/**
181
 * Hook for managing action sheet overlays.
182
 * Returns functions to present and dismiss action sheets.
183
 * @returns [present, dismiss] - Functions to show and hide action sheets
184
 */
185
function useIonActionSheet(): [
186
  (options: ActionSheetOptions) => Promise<void>,
187
  () => void
188
];
189

190
interface ActionSheetOptions {
191
  /** Action sheet header text */
192
  header?: string;
193
  /** Action sheet subheader text */
194
  subHeader?: string;
195
  /** Array of action buttons */
196
  buttons: (string | ActionSheetButton)[];
197
  /** Custom CSS class */
198
  cssClass?: string;
199
  /** Whether clicking backdrop dismisses action sheet */
200
  backdropDismiss?: boolean;
201
  /** Whether action sheet is translucent */
202
  translucent?: boolean;
203
  /** Animation to use when presenting */
204
  enterAnimation?: any;
205
  /** Animation to use when dismissing */
206
  leaveAnimation?: any;
207
}
208

209
interface ActionSheetButton {
210
  /** Button text */
211
  text: string;
212
  /** Button role */
213
  role?: 'cancel' | 'destructive';
214
  /** Button icon */
215
  icon?: any;
216
  /** Custom CSS class */
217
  cssClass?: string;
218
  /** Click handler */
219
  handler?: () => boolean | void | Promise<boolean | void>;
220
}
221
```
222

223
### Popover Management
224

225
Hook for creating and managing popover overlays.
226

227
```typescript { .api }
228
/**
229
 * Hook for managing popover overlays.
230
 * Returns functions to present and dismiss popovers.
231
 * @returns [present, dismiss] - Functions to show and hide popovers
232
 */
233
function useIonPopover(): [
234
  (options: PopoverOptions) => Promise<void>,
235
  () => void
236
];
237

238
interface PopoverOptions {
239
  /** React component to render in popover */
240
  component: React.ComponentType<any>;
241
  /** Props to pass to the component */
242
  componentProps?: any;
243
  /** Element to anchor popover to */
244
  event?: Event;
245
  /** Reference element for positioning */
246
  reference?: 'event' | 'trigger';
247
  /** Side to present popover on */
248
  side?: 'top' | 'right' | 'bottom' | 'left';
249
  /** Alignment relative to reference */
250
  alignment?: 'start' | 'center' | 'end';
251
  /** Whether to show backdrop */
252
  showBackdrop?: boolean;
253
  /** Whether clicking backdrop dismisses popover */
254
  backdropDismiss?: boolean;
255
  /** Custom CSS class */
256
  cssClass?: string;
257
  /** Whether popover is translucent */
258
  translucent?: boolean;
259
}
260
```
261

262
### Loading Management
263

264
Hook for creating and managing loading overlays.
265

266
```typescript { .api }
267
/**
268
 * Hook for managing loading overlays.
269
 * Returns functions to present and dismiss loading indicators.
270
 * @returns [present, dismiss] - Functions to show and hide loading
271
 */
272
function useIonLoading(): [
273
  (options?: LoadingOptions) => Promise<void>,
274
  () => void
275
];
276

277
interface LoadingOptions {
278
  /** Loading message text */
279
  message?: string;
280
  /** Duration in milliseconds (0 = indefinite) */
281
  duration?: number;
282
  /** Spinner type */
283
  spinner?: 'bubbles' | 'circles' | 'circular' | 'crescent' | 'dots' | 'lines' | 'lines-small';
284
  /** Custom CSS class */
285
  cssClass?: string;
286
  /** Whether to show backdrop */
287
  showBackdrop?: boolean;
288
  /** Whether clicking backdrop dismisses loading */
289
  backdropDismiss?: boolean;
290
  /** Whether loading is translucent */
291
  translucent?: boolean;
292
}
293
```
294

295
### Picker Management
296

297
Hook for creating and managing picker overlays.
298

299
```typescript { .api }
300
/**
301
 * Hook for managing picker overlays.
302
 * Returns functions to present and dismiss pickers.
303
 * @returns [present, dismiss] - Functions to show and hide pickers
304
 */
305
function useIonPicker(): [
306
  (options: PickerOptions) => Promise<void>,
307
  () => void
308
];
309

310
interface PickerOptions {
311
  /** Array of picker columns */
312
  columns: PickerColumn[];
313
  /** Array of buttons */
314
  buttons?: PickerButton[];
315
  /** Custom CSS class */
316
  cssClass?: string;
317
  /** Whether to show backdrop */
318
  showBackdrop?: boolean;
319
  /** Whether clicking backdrop dismisses picker */
320
  backdropDismiss?: boolean;
321
  /** Animation to use when presenting */
322
  enterAnimation?: any;
323
  /** Animation to use when dismissing */
324
  leaveAnimation?: any;
325
}
326

327
interface PickerColumn {
328
  /** Column name */
329
  name: string;
330
  /** Array of options */
331
  options: PickerColumnOption[];
332
  /** Selected option index */
333
  selectedIndex?: number;
334
}
335

336
interface PickerColumnOption {
337
  /** Option text */
338
  text: string;
339
  /** Option value */
340
  value: any;
341
  /** Whether option is disabled */
342
  disabled?: boolean;
343
}
344

345
interface PickerButton {
346
  /** Button text */
347
  text: string;
348
  /** Button role */
349
  role?: 'cancel';
350
  /** Custom CSS class */
351
  cssClass?: string;
352
  /** Click handler */
353
  handler?: (value: any) => boolean | void | Promise<boolean | void>;
354
}
355
```
356

357
**Usage Examples:**
358

359
```typescript
360
import React from 'react';
361
import { 
362
  useIonAlert, useIonModal, useIonToast, 
363
  useIonActionSheet, useIonLoading 
364
} from '@ionic/react';
365

366
const OverlayExample: React.FC = () => {
367
  const [presentAlert, dismissAlert] = useIonAlert();
368
  const [presentToast, dismissToast] = useIonToast();
369
  const [presentActionSheet, dismissActionSheet] = useIonActionSheet();
370
  const [presentLoading, dismissLoading] = useIonLoading();
371

372
  const showAlert = () => {
373
    presentAlert({
374
      header: 'Confirm',
375
      message: 'Are you sure?',
376
      buttons: [
377
        {
378
          text: 'Cancel',
379
          role: 'cancel'
380
        },
381
        {
382
          text: 'OK',
383
          handler: () => {
384
            console.log('Confirmed');
385
          }
386
        }
387
      ]
388
    });
389
  };
390

391
  const showToast = () => {
392
    presentToast({
393
      message: 'Hello World!',
394
      duration: 3000,
395
      position: 'bottom'
396
    });
397
  };
398

399
  const showActionSheet = () => {
400
    presentActionSheet({
401
      header: 'Choose Action',
402
      buttons: [
403
        {
404
          text: 'Edit',
405
          handler: () => console.log('Edit')
406
        },
407
        {
408
          text: 'Delete',
409
          role: 'destructive',
410
          handler: () => console.log('Delete')
411
        },
412
        {
413
          text: 'Cancel',
414
          role: 'cancel'
415
        }
416
      ]
417
    });
418
  };
419

420
  const showLoading = async () => {
421
    await presentLoading({
422
      message: 'Please wait...',
423
      duration: 2000
424
    });
425
  };
426

427
  return (
428
    <div>
429
      <IonButton onClick={showAlert}>Show Alert</IonButton>
430
      <IonButton onClick={showToast}>Show Toast</IonButton>
431
      <IonButton onClick={showActionSheet}>Show Action Sheet</IonButton>
432
      <IonButton onClick={showLoading}>Show Loading</IonButton>
433
    </div>
434
  );
435
};
436

437
// Modal example with custom component
438
const ModalContentComponent: React.FC<{ dismiss: () => void }> = ({ dismiss }) => (
439
  <IonPage>
440
    <IonHeader>
441
      <IonToolbar>
442
        <IonTitle>Modal</IonTitle>
443
        <IonButtons slot="end">
444
          <IonButton onClick={dismiss}>Close</IonButton>
445
        </IonButtons>
446
      </IonToolbar>
447
    </IonHeader>
448
    <IonContent>
449
      <p>This is modal content</p>
450
    </IonContent>
451
  </IonPage>
452
);
453

454
const ModalExample: React.FC = () => {
455
  const [presentModal, dismissModal] = useIonModal(ModalContentComponent, {
456
    dismiss: () => dismissModal()
457
  });
458

459
  return (
460
    <IonButton onClick={() => presentModal()}>
461
      Open Modal
462
    </IonButton>
463
  );
464
};
465
```