ons-alert-dialog

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.

Tutorial

Alert dialogs

Alert dialogs are defined using <ons-alert-dialog> and <ons-alert-dialog-button> tags. 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 id="dialog-1">
  <div class="alert-dialog-title">Warning!</div>
  <div class="alert-dialog-content">
    An error has occurred!
  </div>
  <div class="alert-dialog-footer">
    <ons-alert-dialog-button>Cancel</ons-alert-dialog-button>
    <ons-alert-dialog-button>OK</ons-alert-dialog-button>
  </div>
</ons-alert-dialog>

Alert dialogs are hidden by default and usually attached as direct children of the <body> tag.

Displaying an alert dialog

To display an alert 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.

Loading from a template

Another way to use alert dialogs is with the ons.createElement(template) utility function. The dialog needs to be defined as a template (or a separate file) and the function returns a Promise that resolves to the dialog element.

<template id="dialog.html">
  <ons-alert-dialog>
    This dialog is defined as a template.
  </ons-alert-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.

The “cancelable” attribute

<ons-alert-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-alert-dialog cancelable>
  This dialog can be cancelled!
</ons-alert-dialog>

Try adding the cancelable attribute to the dialog to see how it works.

Notification

Another way to display alert dialogs is with the ons.notification methods:

  • ons.notification.alert(options)
  • ons.notification.confirm(options)
  • ons.notification.prompt(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);
  });

See also

Attributes are added directly to the element. You can do this in HTML or JS.

HTML: <ons-alert-dialog someAttribute="true" anotherAttribute><ons-alert-dialog>
JS: document.querySelector('ons-alert-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 alert 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-alert-dialog').disabled.

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'}.

Modifiers are set in the modifier attribute. To use more than one, separate them by spaces. For example:
<ons-alert-dialog modifier="material rowfooter"><ons-alert-dialog>.

Name Description
material Material Design style
rowfooter Horizontally aligns the footer buttons.

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-alert-dialog').someMethod().

Signature Description
show([options]) Show the alert dialog.
hide([options]) Hide the alert dialog.
show([options]): Promise

Show the alert dialog.

Returns: A Promise object that resolves to the displayed element.

Parameters
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([options]): Promise

Hide the alert dialog.

Returns: Resolves to the hidden element

Parameters
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.

To use these events, add event listeners to the elements as you would for native events, like click. For example: document.querySelector('ons-alert-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 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.
preshow

Fired just before the alert dialog is displayed.

Parameters
Name Type Description
event Object Event object.
event.alertDialog Object Alert dialog object.
event.cancel Function Execute to stop the dialog from showing.
postshow

Fired just after the alert dialog is displayed.

Parameters
Name Type Description
event Object Event object.
event.alertDialog Object Alert dialog object.
prehide

Fired just before the alert dialog is hidden.

Parameters
Name Type Description
event Object Event object.
event.alertDialog Object Alert dialog object.
event.cancel Function Execute to stop the dialog from hiding.
posthide

Fired just after the alert dialog is hidden.

Parameters
Name Type Description
event Object Event object.
event.alertDialog Object Alert dialog object.
dialogcancel

Fired when the dialog is canceled.

Parameters
Name Type Description

Need Help?

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.