Dialog that is displayed on top of current screen. As opposed to the <ons-alert-dialog> element, this component can contain any kind of content.
To use the element it can either be attached directly to the <body> element or dynamically created from a template using the ons.createDialog(template) utility function and the <template> tag.
The dialog is useful for displaying menus, additional information or to ask the user to make a decision.
It will automatically be displayed as Material Design when running on an Android device.
Normal dialogs are defined using the <ons-dialog> tag.
<ons-dialog id="dialog-1">
This is a dialog!
</ons-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.
document
.getElementById('dialog-1')
.show();
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();
});
Do not forget attaching the created dialog to the DOM. This can be done by passing append options to ons.createElement.
<ons-dialog> supports 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 the dialog to see how it works.
The <ons-dialog> element can get as complex as we need. It can contain pages or even navigators:
<ons-dialog>
<ons-page>
<ons-toolbar>...</ons-toolbar>
...
</ons-page>
</ons-dialog>
Attributes are added directly to the element. You can do this in HTML or JS.
HTML: <ons-dialog someAttribute="true" anotherAttribute><ons-dialog>
JS: document.querySelector('ons-dialog').setAttribute('someAttribute', 'true')
| 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 dialog is visible or not. Optional. |
Properties are accessed on the element through JS, and should be get and set directly. For example: document.querySelector('ons-dialog').animationOptions.
| Name | Description |
|---|---|
| animationOptions |
Specify the animation’s duration, timing and delay with an object literal. E.g. {duration: 0.2, delay: 1, timing: 'ease-in'}.
|
| onDeviceBackButton | Back-button handler. |
| visible | Whether the dialog is visible or not. |
| disabled | Whether the dialog 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)”. |
Modifiers are set in the modifier attribute. To use more than one, separate them by spaces. For example:
<ons-dialog modifier="material
modifier2"><ons-dialog>.
| Name | Description |
|---|---|
| material | Display a Material Design dialog. |
These methods are called directly on the DOM element. Get a reference to the element in JS, and the methods below will be available to call on it. For example: document.querySelector('ons-dialog').someMethod().
| Signature | Description |
|---|---|
| show([options]) | Show the dialog. |
| hide([options]) | Hide the dialog. |
Show the dialog.
Returns:
| Name | Type | Description |
|---|---|---|
| options | Object | Parameter object. |
| options.animation | String |
Animation name. Available animations are "none" and "slide".
|
| 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 | This function is called after the dialog has been revealed. |
Hide the dialog.
Returns: Resolves to the hidden element
| Name | Type | Description |
|---|---|---|
| options | Object | Parameter object. |
| options.animation | String |
Animation name. Available animations are "none" and "slide".
|
| 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 | This functions is called after the dialog has been hidden. |
To use these events, add event listeners to the elements as you would for native events, like click. For example: document.querySelector('ons-dialog').addEventListener('preshow', function() { ... }).
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 dialog is displayed. |
| postshow | Fired just after the dialog is displayed. |
| prehide | Fired just before the dialog is hidden. |
| posthide | Fired just after the dialog is hidden. |
| dialogcancel | Fired when the dialog is canceled. |
Fired just before the dialog is displayed.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.dialog | Object | Component object. |
| event.cancel | Function | Execute this function to stop the dialog from being shown. |
Fired just after the dialog is displayed.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.dialog | Object | Component object. |
Fired just before the dialog is hidden.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.dialog | Object | Component object. |
| event.cancel | Function | Execute this function to stop the dialog from being hidden. |
Fired just after the dialog is hidden.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.dialog | Object | Component 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.