Alert

Improve this doc

An Alert is a dialog that presents users with information or collects information from the user using inputs. An alert appears on top of the app's content, and must be manually dismissed by the user before they can resume interaction with the app. It can also optionally have a title, subTitle and message.

You can pass all of the alert's options in the first argument of the create method: Alert.create(opts). Otherwise the alert's instance has methods to add options, such as setTitle() or addButton().

Alert Buttons

In the array of buttons, each button includes properties for its text, and optionally a handler. If a handler returns false then the alert will not automatically be dismissed when the button is clicked. All buttons will show up in the order they have been added to the buttons array, from left to right. Note: The right most button (the last one in the array) is the main button.

Optionally, a role property can be added to a button, such as cancel. If a cancel role is on one of the buttons, then if the alert is dismissed by tapping the backdrop, then it will fire the handler from the button with a cancel role.

Alert Inputs

Alerts can also include several different inputs whose data can be passed back to the app. Inputs can be used as a simple way to prompt users for information. Radios, checkboxes and text inputs are all accepted, but they cannot be mixed. For example, an alert could have all radio button inputs, or all checkbox inputs, but the same alert cannot mix radio and checkbox inputs. Do note however, different types of "text"" inputs can be mixed, such as url, email, text, etc. If you require a complex form UI which doesn't fit within the guidelines of an alert then we recommend building the form within a modal instead.

Usage

constructor(nav: NavController) {
  this.nav = nav;
}

presentAlert() {
  let alert = Alert.create({
    title: 'Low battery',
    subTitle: '10% of battery remaining',
    buttons: ['Dismiss']
  });
  this.nav.present(alert);
}

presentConfirm() {
  let alert = Alert.create({
    title: 'Confirm purchase',
    message: 'Do you want to buy this book?',
    buttons: [
      {
        text: 'Cancel',
        role: 'cancel',
        handler: () => {
          console.log('Cancel clicked');
        }
      },
      {
        text: 'Buy',
        handler: () => {
          console.log('Buy clicked');
        }
      }
    ]
  });
  this.nav.present(alert);
}

presentPrompt() {
  let alert = Alert.create({
    title: 'Login',
    inputs: [
      {
        name: 'username',
        placeholder: 'Username'
      },
      {
        name: 'password',
        placeholder: 'Password',
        type: 'password'
      }
    ],
    buttons: [
      {
        text: 'Cancel',
        role: 'cancel',
        handler: data => {
          console.log('Cancel clicked');
        }
      },
      {
        text: 'Login',
        handler: data => {
          if (User.isValid(data.username, data.password)) {
            // logged in!
          } else {
            // invalid login
            return false;
          }
        }
      }
    ]
  });
  this.nav.present(alert);
}

Dismissing And Async Navigation

After an alert has been dismissed, the app may need to also transition to another page depending on the handler's logic. However, because multiple transitions were fired at roughly the same time, it's difficult for the nav controller to cleanly animate multiple transitions that may have been kicked off asynchronously. This is further described in the Nav Transition Promises section. For alerts, this means it's best to wait for the alert to finish its transition out before starting a new transition on the same nav controller.

In the example below, after the alert button has been clicked, its handler waits on async operation to complete, then it uses pop to navigate back a page in the same stack. The potential problem is that the async operation may have been completed before the alert has even finished its transition out. In this case, it's best to ensure the alert has finished its transition out first, then start the next transition.

let alert = Alert.create({
  title: 'Hello',
  buttons: [{
    text: 'Ok',
    handler: () => {
      // user has clicked the alert button
      // begin the alert's dimiss transition
      let navTransition = alert.dismiss();

      // start some async method
      someAsyncOperation().then(() => {
        // once the async operation has completed
        // then run the next nav transition after the
        // first transition has finished animating out

        navTransition.then(() => {
          this.nav.pop();
        });
      });
      return false;
    }
  }]
});

this.nav.present(alert);

It's important to note that the handler returns false. A feature of button handlers is that they automatically dismiss the alert when their button was clicked, however, we'll need more control regarding the transition. Because the handler returns false, then the alert does not automatically dismiss itself. Instead, you now have complete control of when the alert has finished transitioning, and the ability to wait for the alert to finish transitioning out before starting a new transition.

Static Members

create(opts)

Alert options

Property Type Description
title string The string for the alert (optional)
subTitle string The subtitle for the alert (optional)
message string The message for the alert (optional)
cssClass string Any additional class for the alert (optional)
inputs array An array of inputs for the alert. See input options. (optional)
buttons array An array of buttons for the alert. See buttons options. (optional)
enableBackdropDismiss boolean Wheather the alert should be dismissed by tapping the backdrop (optional)

Input options

Property Type Description
type string The type the input should be, text, tel, number, etc (optional)
name string The name for the input (optional)
placeHolder string The input’s placeholder (optional)
value string The input’s value (optional)
label string The input’s label (optional)
checked boolean Whether or not the input is checked or not (optional)
id string The input’s id (optional)

Button options

Property Type Description
text string The buttons displayed text
handler any Expression that should be evaluated when the button is pressed
cssClass string An additional CSS class for the button
role string The buttons role, null or cancel
Param Type Details
opts object

Alert. See the table above

Instance Members

setTitle(title)

Param Type Details
title string

Alert title

setSubTitle(subTitle)

Param Type Details
subTitle string

Alert subtitle

setMessage(message)

Param Type Details
message string

Alert message content

addInput(input)

Param Type Details
input object

Alert input

addButton(button)

Param Type Details
button any

Alert button

setCssClass(cssClass)

Param Type Details
cssClass string

CSS class name to add to the alert's outer wrapper

API

Native

General