Alert dialog that is displayed on top of the current screen. Useful for displaying questions, warnings or error messages to the user. The title, content and buttons can be easily customized and it will automatically switch style based on the platform.
To use the element it can either be attached directly to the <body> element or dynamically created from a template using the ons.createAlertDialog(template) utility function and the <template> tag.
Dialogs are defined using the <ons-dialog>, <ons-alert-dialog> and <ons-toast> tags.
<ons-dialog var="dialog">
This is a dialog!
</ons-dialog>
var attribute is used to store the dialog in a variable for later access.
Alert dialogs work exactly like normal dialogs but they require some additional markup. With this element you can create a beautifully styled dialog without any additional CSS.
<ons-alert-dialog>
<div class="alert-dialog-title">Warning!</div>
<div class="alert-dialog-content">
An error has occurred!
</div>
<div class="alert-dialog-footer">
<button class="alert-dialog-button">Cancel</button>
<button class="alert-dialog-button">OK</button>
</div>
</ons-alert-dialog>
Dialogs are hidden by default and usually attached as direct children of the <body> tag.
To display a dialog you need to get a reference to the element and execute the show(options) method.
It is hidden with the hide(options) method.
Another way to use dialogs is with the ons.createElement(template) utility function. The dialog needs to be defined as a template and the function returns a Promise that resolves to the dialog element.
<template id="dialog.html">
<ons-dialog>
This dialog is defined as a template.
</ons-dialog>
</template>
ons
.createElement('dialog.html', { append: true })
.then(function(dialog) {
dialog.show();
});
For AngularJS, an extra parameter can be passed to specify the scope of the new popover: ons.createElement('dialog.html', { parentScope: $scope });
cancelable attributeThe <ons-dialog>, <ons-alert-dialog> and <ons-toast> support the cancelable attribute. This enables hiding the dialog by tapping outside of it or by pressing the back button on Android devices.
<ons-dialog cancelable>
This dialog can be cancelled!
</ons-dialog>
Try adding the cancelable attribute to one of the dialogs to see how it works.
Another way to display dialogs is with the ons.notification methods:
ons.notification.alert(options)ons.notification.confirm(options)ons.notification.prompt(options)ons.notification.toast(options)These methods all return a Promise. For the confirm it resolves to the index of the button pressed and for the prompt it resolves to the user input.
ons
.notification.prompt({message: 'What is your name?'})
.then(function(name) {
ons.notification.alert('Hello ' + name);
});
| Name | Type | Description |
|---|---|---|
| modifier | String | The appearance of the dialog. Optional. |
| cancelable | If this attribute is set the dialog can be closed by tapping the background or by pressing the back button on Android devices. Optional. | |
| disabled | If this attribute is set the dialog is disabled. Optional. | |
| animation |
String
default |
The animation used when showing and hiding the dialog. Can be either "none" or "default".
Optional.
|
| animation-options | Expression |
Specify the animation’s duration, timing and delay with an object literal. E.g. {duration: 0.2, delay: 1, timing: 'ease-in'}.
Optional.
|
| mask-color |
String
rgba(0, 0, 0, 0.2) |
Color of the background mask. Default is “rgba(0, 0, 0, 0.2)”. Optional. |
| visible | Boolean | Whether the alert dialog is visible or not. Optional. |
| var | String | Variable name to refer this alert dialog. Optional. Works only during initialization. |
| ons-preshow | Expression | Allows you to specify custom behavior when the “preshow” event is fired. Optional. Works only during initialization. |
| ons-prehide | Expression | Allows you to specify custom behavior when the “prehide” event is fired. Optional. Works only during initialization. |
| ons-postshow | Expression | Allows you to specify custom behavior when the “postshow” event is fired. Optional. Works only during initialization. |
| ons-posthide | Expression | Allows you to specify custom behavior when the “posthide” event is fired. Optional. Works only during initialization. |
| ons-destroy | Expression | Allows you to specify custom behavior when the “destroy” event is fired. Optional. Works only during initialization. |
| Name | Description |
|---|---|
| disabled | Whether the element is disabled or not. |
| cancelable | Whether the dialog is cancelable or not. A cancelable dialog can be closed by tapping the background or by pressing the back button on Android devices. |
| maskColor | Color of the background mask. Default is “rgba(0, 0, 0, 0.2)”. |
| visible | Whether the dialog is visible or not. |
| onDeviceBackButton | Back-button handler. |
| animationOptions |
Specify the animation’s duration, timing and delay with an object literal. E.g. {duration: 0.2, delay: 1, timing: 'ease-in'}.
|
| Name | Description |
|---|---|
| material | Material Design style |
| rowfooter | Horizontally aligns the footer buttons. |
| Signature | Description |
|---|---|
| show([options]) | Show the alert dialog. |
| hide([options]) | Hide the alert dialog. |
| on(eventName, listener) | Add an event listener. |
| once(eventName, listener) | Add an event listener that’s only triggered once. |
| off(eventName, [listener]) | Remove an event listener. If the listener is not specified all listeners for the event type will be removed. |
Show the alert dialog.
Returns: A Promise object that resolves to the displayed element.
| Name | Type | Description |
|---|---|---|
| options | Object | Parameter object. |
| options.animation | String |
Animation name. Available animations are "fade" and "none".
|
| options.animationOptions | String |
Specify the animation’s duration, delay and timing. E.g. {duration: 0.2, delay: 0.4, timing: 'ease-in'}.
|
| options.callback | Function | Function to execute after the dialog has been revealed. |
Hide the alert dialog.
Returns: Resolves to the hidden element
| Name | Type | Description |
|---|---|---|
| options | Object | Parameter object. |
| options.animation | String |
Animation name. Available animations are "fade" and "none".
|
| options.animationOptions | String |
Specify the animation’s duration, delay and timing. E.g. {duration: 0.2, delay: 0.4, timing: ‘ease-in’}
|
| options.callback | Function | Function to execute after the dialog has been hidden. |
Add an event listener.
| Name | Type | Description |
|---|---|---|
| eventName | String | Name of the event. |
| listener | Function | Function to execute when the event is triggered. |
Add an event listener that’s only triggered once.
| Name | Type | Description |
|---|---|---|
| eventName | String | Name of the event. |
| listener | Function | Function to execute when the event is triggered. |
Remove an event listener. If the listener is not specified all listeners for the event type will be removed.
| Name | Type | Description |
|---|---|---|
| eventName | String | Name of the event. |
| listener | Function | Function to execute when the event is triggered. |
Some Onsen UI components have overlapping event names. For example, ons-carousel and ons-navigator both emit postchange events. Stop overlapping events from propagating to avoid conflicts: document.querySelector('ons-carousel').on('postchange', e => e.stopPropagation()).
| Name | Description |
|---|---|
| preshow | Fired just before the alert dialog is displayed. |
| postshow | Fired just after the alert dialog is displayed. |
| prehide | Fired just before the alert dialog is hidden. |
| posthide | Fired just after the alert dialog is hidden. |
| dialogcancel | Fired when the dialog is canceled. |
Fired just before the alert dialog is displayed.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.alertDialog | Object | Alert dialog object. |
| event.cancel | Function | Execute to stop the dialog from showing. |
Fired just after the alert dialog is displayed.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.alertDialog | Object | Alert dialog object. |
Fired just before the alert dialog is hidden.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.alertDialog | Object | Alert dialog object. |
| event.cancel | Function | Execute to stop the dialog from hiding. |
Fired just after the alert dialog is hidden.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.alertDialog | Object | Alert dialog object. |
Fired when the dialog is canceled.
| Name | Type | Description |
|---|
If you have any questions, use our Community Forum or talk to us on Discord chat. The Onsen UI team and your peers in the community will work together to help solve your issues.
For bug reports and feature requests use our GitHub Issues page.