ons.notification

Utility methods to create different kinds of notifications. There are three methods available:

  • ons.notification.alert()
  • ons.notification.confirm()
  • ons.notification.prompt()
  • ons.notification.toast() It will automatically display a Material Design dialog on Android devices.

Tutorial

Notifications

Dialogs can be displayed 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);
  });

Alternatively, dialogs can be created with the <ons-dialog>, <ons-alert-dialog> and <ons-toast> elements.

Signature Description
alert(message [, options] | options)

Display an alert dialog to show the user a message. The content of the message can be either simple text or HTML. It can be called in the following ways:

  ons.notification.alert(message, options);
  ons.notification.alert(options);

Must specify either message or messageHTML.

confirm(message [, options] | options)

Display a dialog to ask the user for confirmation. Extends alert() parameters. The default button labels are "Cancel" and "OK" but they can be customized. It can be called in the following ways:

  ons.notification.confirm(message, options);
  ons.notification.confirm(options);

Must specify either message or messageHTML.

prompt(message [, options] | options)

Display a dialog with a prompt to ask the user a question. Extends alert() parameters. It can be called in the following ways:

  ons.notification.prompt(message, options);
  ons.notification.prompt(options);

Must specify either message or messageHTML.

toast(message [, options] | options)

Display a simple notification toast with an optional button that can be used for simple actions. It can be called in the following ways:

  ons.notification.toast(message, options);
  ons.notification.toast(options);
alert(message [, options] | options): Promise

Display an alert dialog to show the user a message. The content of the message can be either simple text or HTML. It can be called in the following ways:

  ons.notification.alert(message, options);
  ons.notification.alert(options);

Must specify either message or messageHTML.

Returns: Will resolve to the index of the button that was pressed or -1 when canceled.

Parameters
Name Type Description
message String Notification message. This argument is optional but if it’s not defined either options.message or options.messageHTML must be defined instead.
options Object Parameter object.
options.message String Notification message.
options.messageHTML String Notification message in HTML.
options.buttonLabels String | Array Labels for the buttons. Default is "OK".
options.primaryButtonIndex Number Index of primary button. Default is the last one.
options.cancelable Boolean Whether the dialog is cancelable or not. Default is false. If the dialog is cancelable it can be closed by clicking the background or pressing the Android back button.
options.animation String Animation name. Available animations are none and fade. Default is fade.
options.id String The <ons-alert-dialog> element’s ID.
options.class String The <ons-alert-dialog> element’s class.
options.title String Dialog title. Default is "Alert".
options.modifier String Modifier for the dialog.
options.maskColor String Color of the background mask. Default is “rgba(0, 0, 0, 0.2)” (“rgba(0, 0, 0, 0.3)” for Material).
options.callback Function Function that executes after dialog has been closed.
confirm(message [, options] | options): Promise

Display a dialog to ask the user for confirmation. Extends alert() parameters. The default button labels are "Cancel" and "OK" but they can be customized. It can be called in the following ways:

  ons.notification.confirm(message, options);
  ons.notification.confirm(options);

Must specify either message or messageHTML.

Returns: Will resolve to the index of the button that was pressed or -1 when canceled.

Parameters
Name Type Description
message String Notification message. This argument is optional but if it’s not defined either options.message or options.messageHTML must be defined instead.
options Object Parameter object.
options.buttonLabels Array Labels for the buttons. Default is ["Cancel", "OK"].
options.primaryButtonIndex Number Index of primary button. Default is the last one.
prompt(message [, options] | options): Promise

Display a dialog with a prompt to ask the user a question. Extends alert() parameters. It can be called in the following ways:

  ons.notification.prompt(message, options);
  ons.notification.prompt(options);

Must specify either message or messageHTML.

Returns: Will resolve to the input value when the dialog is closed or null when canceled.

Parameters
Name Type Description
message String Notification message. This argument is optional but if it’s not defined either options.message or options.messageHTML must be defined instead.
options Object Parameter object.
options.buttonLabels String | Array Labels for the buttons. Default is "OK".
options.primaryButtonIndex Number Index of primary button. Default is the last one.
options.placeholder String Placeholder for the text input.
options.defaultValue String Default value for the text input.
options.inputType String Type of the input element (password, date…). Default is text.
options.autofocus Boolean Autofocus the input element. Default is true. In Cordova, KeyboardDisplayRequiresUserAction in config.xml must be false to activate this feature.
options.submitOnEnter Boolean Submit automatically when enter is pressed. Default is true.
toast(message [, options] | options): Promise

Display a simple notification toast with an optional button that can be used for simple actions. It can be called in the following ways:

  ons.notification.toast(message, options);
  ons.notification.toast(options);

Returns: Will resolve when the toast is hidden.

Parameters
Name Type Description
message String Toast message. This argument is optional but if it’s not defined then options.message must be defined instead.
options Object Parameter object.
options.message String Notification message.
options.buttonLabel String Label for the button.
options.animation String Animation name. Available animations are none, fade, ascend, lift and fall. Default is ascend for Android and lift for iOS.
options.timeout Number Number of miliseconds where the toast is visible before hiding automatically.
options.force Boolean If true, the toast skips the notification queue and is shown immediately. Defaults to false.
options.id String The <ons-toast> element’s ID.
options.class String The <ons-toast> element’s class.
options.modifier String Modifier for the element.
options.callback Function Function that executes after toast has been hidden.

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.