Need help upgrading to Ionic Framework 4.0? Get assistance with our Enterprise Migration Services EXPLORE NOW

AlertController

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: 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(private alertCtrl: AlertController) {

}

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

presentConfirm() {
  let alert = this.alertCtrl.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');
        }
      }
    ]
  });
  alert.present();
}

presentPrompt() {
  let alert = this.alertCtrl.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;
          }
        }
      }
    ]
  });
  alert.present();
}

Instance Members

create(opts)

Display an alert with a title, inputs, and buttons

Param Type Details
opts AlertOptions

Alert. See the table below

Advanced

Alert options

Property Type Description
title string The title for the alert.
subTitle string The subtitle for the alert.
message string The message for the alert.
cssClass string Additional classes for custom styles, separated by spaces.
inputs array An array of inputs for the alert. See input options.
buttons array An array of buttons for the alert. See buttons options.
enableBackdropDismiss boolean Whether the alert should be dismissed by tapping the backdrop.

Input options

Property Type Description
type string The type the input should be: text, tel, number, etc.
name string The name for the input.
placeholder string The input's placeholder (for textual/numeric inputs)
value string The input's value.
label string The input's label (only for radio/checkbox inputs)
checked boolean Whether or not the input is checked.
id string The input's id.

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.

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 = this.alertCtrl.create({
  title: 'Hello',
  buttons: [{
    text: 'Ok',
    handler: () => {
      // user has clicked the alert button
      // begin the alert's dismiss 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;
    }
  }]
});

alert.present();

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.

Sass Variables

Property Default Description
$alert-ios-max-width 270px

Max width of the alert

$alert-ios-border-radius 13px

Border radius of the alert

$alert-ios-background #f8f8f8

Background color of the alert

$alert-ios-box-shadow none

Box shadow of the alert

$alert-ios-head-padding 12px 16px 7px

Padding of the alert head

$alert-ios-head-text-align center

Text align of the alert head

$alert-ios-title-margin-top 8px

Margin top of the alert title

$alert-ios-title-font-size 17px

Font size of the alert title

$alert-ios-title-font-weight 600

Font weight of the alert title

$alert-ios-sub-title-font-size 14px

Font size of the alert sub title

$alert-ios-sub-title-text-color #666

Text color of the alert sub title

$alert-ios-message-padding 0 16px 21px

Padding of the alert message

$alert-ios-message-font-size 13px

Font size of the alert message

$alert-ios-message-text-align center

Text align of the alert message

$alert-ios-message-text-color inherit

Text color of the alert message

$alert-ios-message-padding-empty 0 0 12px 0

Padding of the alert empty message

$alert-ios-content-max-height 240px

Maximum height of the alert content

$alert-ios-input-margin-top 10px

Margin top of the alert input

$alert-ios-input-padding 6px

Padding on the alert input

$alert-ios-input-border-color #ccc

Border color of the alert input

$alert-ios-input-border $hairlines-width solid $alert-ios-input-border-color

Border of the alert input

$alert-ios-input-border-radius 4px

Border radius of the alert input

$alert-ios-input-background-color #fff

Background color of the alert input

$alert-ios-button-group-flex-wrap wrap

Flex wrap of the alert button group

$alert-ios-button-flex 1 1 auto

Flex of the alert button

$alert-ios-button-margin 0

Margin of the alert button

$alert-ios-button-min-width 50%

Min width of the alert button

$alert-ios-button-min-height 44px

Minimum height of the alert button

$alert-ios-button-font-size 17px

Font size of the alert button

$alert-ios-button-text-color color($colors-ios, primary)

Color of the text in the alert button

$alert-ios-button-background-color transparent

Background color of the alert button

$alert-ios-button-background-color-activated #e9e9e9

Background color of the alert activated button

$alert-ios-button-border-width $hairlines-width

Border width of the alert button

$alert-ios-button-border-style solid

Border style of the alert button

$alert-ios-button-border-color #dbdbdf

Border color of the alert button

$alert-ios-button-border-radius 0

Border radius of the alert button

$alert-ios-button-main-font-weight bold

Font weight of the main text on the alert button

$alert-ios-list-border-top $alert-ios-button-border-width $alert-ios-button-border-style $alert-ios-button-border-color

Border top of the alert list

$alert-ios-radio-label-padding 13px

Padding on the label for the radio alert

$alert-ios-radio-label-text-color-checked $alert-ios-button-text-color

Text color of the label for the checked radio alert

$alert-ios-radio-min-width 30px

Min width of the radio alert

$alert-ios-radio-icon-top -7px

Top of the icon in the radio alert

$alert-ios-radio-icon-left 7px

Left of the icon in the radio alert

$alert-ios-radio-icon-width 6px

Width of the icon in the radio alert

$alert-ios-radio-icon-height 12px

Height of the icon in the radio alert

$alert-ios-radio-icon-border-width 2px

Border width of the icon in the radio alert

$alert-ios-radio-icon-border-style solid

Border style of the icon in the radio alert

$alert-ios-radio-icon-border-color $alert-ios-button-text-color

Border color of the icon in the radio alert

$alert-ios-radio-icon-transform rotate(45deg)

Transform of the icon in the radio alert

$alert-ios-checkbox-label-padding 13px

Padding of the label for the checkbox in the alert

$alert-ios-checkbox-label-text-color-checked initial

Text color of the label for the checked checkbox in the alert

$alert-ios-checkbox-margin 10px 6px 10px 16px

Margin of the checkbox in the alert

$alert-ios-checkbox-size 21px

Size of the checkbox in the alert

$alert-ios-checkbox-border-width $hairlines-width

Border width of the checkbox in the alert

$alert-ios-checkbox-border-style solid

Border style of the checkbox in the alert

$alert-ios-checkbox-border-radius 50%

Border radius of the checkbox in the alert

$alert-ios-checkbox-border-color-off $list-ios-border-color

Border color of the checkbox in the alert when off

$alert-ios-checkbox-border-color-on color($colors-ios, primary)

Border color of the checkbox in the alert when on

$alert-ios-checkbox-background-color-off $list-ios-background-color

Background color of the checkbox in the alert when off

$alert-ios-checkbox-background-color-on color($colors-ios, primary)

Background color of the checkbox in the alert when on

$alert-ios-checkbox-icon-top 4px

Top of the icon in the checkbox alert

$alert-ios-checkbox-icon-left 7px

Left of the icon in the checkbox alert

$alert-ios-checkbox-icon-width 4px

Width of the icon in the checkbox alert

$alert-ios-checkbox-icon-height 9px

Height of the icon in the checkbox alert

$alert-ios-checkbox-icon-border-width $alert-ios-checkbox-border-width

Border width of the icon in the checkbox alert

$alert-ios-checkbox-icon-border-style $alert-ios-checkbox-border-style

Border style of the icon in the checkbox alert

$alert-ios-checkbox-icon-border-color $background-ios-color

Border color of the icon in the checkbox alert

$alert-ios-checkbox-icon-transform rotate(45deg)

Transform of the icon in the checkbox alert

Property Default Description
$alert-md-max-width 280px

Max width of the alert

$alert-md-border-radius 2px

Border radius of the alert

$alert-md-background-color #fafafa

Background color of the alert

$alert-md-box-shadow-color rgba(0, 0, 0, .4)

Box shadow color of the alert

$alert-md-box-shadow 0 16px 20px $alert-md-box-shadow-color

Box shadow of the alert

$alert-md-head-padding 24px 24px 20px 24px

Padding of the alert head

$alert-md-head-text-align left

Text align of the alert head

$alert-md-title-font-size 22px

Font size of the alert title

$alert-md-sub-title-font-size 16px

Font size of the alert sub title

$alert-md-message-padding 0 24px 24px 24px

Padding of the alert message

$alert-md-message-font-size 15px

Font size of the alert message

$alert-md-message-text-color rgba(0, 0, 0, .5)

Text color of the alert message

$alert-md-message-padding-empty 0

Padding of the alert empty message

$alert-md-content-max-height 240px

Maximum height of the alert content

$alert-md-input-border-width 1px

Border width of the alert input

$alert-md-input-border-style solid

Border style of the alert input

$alert-md-input-border-color #dedede

Border color of the alert input

$alert-md-input-text-color #000

Text color of the alert input

$alert-md-input-border-width-focused 2px

Border width of the alert input when focused

$alert-md-input-border-style-focused $alert-md-input-border-style

Border style of the alert input when focused

$alert-md-input-border-color-focused color($colors-md, primary)

Border color of the alert input when focused

$alert-md-input-margin-top 5px

Margin top of the alert input

$alert-md-input-margin-right 0

Margin right of the alert input

$alert-md-input-margin-bottom 5px

Margin bottom of the alert input

$alert-md-input-margin-left 0

Margin left of the alert input

$alert-md-button-group-flex-wrap wrap-reverse

Flex wrap of the alert button group

$alert-md-button-group-padding 8px 8px 8px 24px

Padding of the alert button group

$alert-md-button-group-justify-content flex-end

Justify content of the alert button group

$alert-md-button-padding 10px

Padding of the alert button

$alert-md-button-margin 0 8px 0 0

Margin of the alert button

$alert-md-button-font-weight 500

Font weight of the alert button

$alert-md-button-text-color color($colors-md, primary)

Text color of the alert button

$alert-md-button-background-color transparent

Background color of the alert button

$alert-md-button-background-color-activated rgba(158, 158, 158, .2)

Background color of the alert activated button

$alert-md-button-border-radius 2px

Border radius of the alert button

$alert-md-button-text-transform uppercase

Text transform of the alert button

$alert-md-button-text-align right

Text align of the alert button

$alert-md-list-border-top 1px solid $alert-md-input-border-color

Border top of the alert list

$alert-md-list-border-bottom $alert-md-list-border-top

Border bottom of the alert list

$alert-md-radio-label-padding 13px 26px

Padding on the label for the radio alert

$alert-md-radio-label-text-color-checked $alert-md-button-text-color

Text color of the label for the checked radio alert

$alert-md-radio-top 0

Top of the alert radio

$alert-md-radio-left 13px

Left of the alert radio

$alert-md-radio-width 16px

Width of the alert radio

$alert-md-radio-height 16px

Height of the alert radio

$alert-md-radio-border-width 2px

Border width of the alert radio

$alert-md-radio-border-style solid

Border style of the alert radio

$alert-md-radio-border-radius 50%

Border radius of the alert radio

$alert-md-radio-border-color-off darken($list-md-border-color, 40%)

Border color of the alert radio when off

$alert-md-radio-border-color-on $alert-md-button-text-color

Border color of the alert radio when on

$alert-md-radio-icon-top 2px

Top of the icon in the alert radio

$alert-md-radio-icon-left 2px

Left of the icon in the alert radio

$alert-md-radio-icon-width 8px

Width of the icon in the alert radio

$alert-md-radio-icon-height 8px

Height of the icon in the alert radio

$alert-md-radio-icon-border-radius $alert-md-radio-border-radius

Border radius of the icon in the alert radio

$alert-md-radio-icon-transform-off scale3d(0, 0, 0)

Transform of the icon in the alert radio when off

$alert-md-radio-icon-transform-on scale3d(1, 1, 1)

Transform of the icon in the alert radio when on

$alert-md-radio-icon-transition transform 280ms cubic-bezier(.4, 0, .2, 1)

Transition of the icon in the alert radio

$alert-md-checkbox-label-padding 13px 26px

Padding of the label for the checkbox in the alert

$alert-md-checkbox-label-text-color-checked initial

Text color of the label for the checked checkbox in the alert

$alert-md-checkbox-top 0

Top of the checkbox in the alert

$alert-md-checkbox-left 13px

Left of the checkbox in the alert

$alert-md-checkbox-width 16px

Width of the checkbox in the alert

$alert-md-checkbox-height 16px

Height of the checkbox in the alert

$alert-md-checkbox-border-width 2px

Border width of the checkbox in the alert

$alert-md-checkbox-border-style solid

Border style of the checkbox in the alert

$alert-md-checkbox-border-radius 2px

Border radius of the checkbox in the alert

$alert-md-checkbox-border-color-off darken($list-md-border-color, 40%)

Border color of the checkbox in the alert when off

$alert-md-checkbox-border-color-on $alert-md-button-text-color

Border color of the checkbox in the alert when on

$alert-md-checkbox-icon-top 0

Top of the icon in the checkbox alert

$alert-md-checkbox-icon-left 3px

Left of the icon in the checkbox alert

$alert-md-checkbox-icon-width 6px

Width of the icon in the checkbox alert

$alert-md-checkbox-icon-height 10px

Height of the icon in the checkbox alert

$alert-md-checkbox-icon-border-width 2px

Border width of the icon in the checkbox alert

$alert-md-checkbox-icon-border-style solid

Border style of the icon in the checkbox alert

$alert-md-checkbox-icon-border-color color-contrast($colors-md, $alert-md-checkbox-border-color-on)

Border color of the icon in the checkbox alert

$alert-md-checkbox-icon-transform rotate(45deg)

Transform of the icon in the checkbox alert

Property Default Description
$alert-wp-backdrop-background #fff

Background of the alert backdrop

$alert-wp-width 100%

Width of the alert

$alert-wp-max-width 520px

Max width of the alert

$alert-wp-border-width 1px

Border width of the alert

$alert-wp-border-style solid

Border style of the alert

$alert-wp-border-color color($colors-wp, primary)

Border color of the alert

$alert-wp-border-radius 0

Border radius of the alert

$alert-wp-background #e6e6e6

Background color of the alert

$alert-wp-head-padding 20px 22px 5px 22px

Padding of the alert head

$alert-wp-head-text-align left

Text align of the alert head

$alert-wp-title-font-size 20px

Font size of the alert title

$alert-wp-title-font-weight 400

Font weight of the alert title

$alert-wp-sub-title-font-size 16px

Font size of the alert sub title

$alert-wp-message-padding 0 22px 8px 22px

Padding of the alert message

$alert-wp-message-padding-empty 0

Padding of the alert empty message

$alert-wp-message-text-color #000

Text color of the alert message

$alert-wp-message-font-size 13px

Font size of the alert message

$alert-wp-content-max-height 240px

Maximum height of the alert content

$alert-wp-input-margin 5px 0 5px 0

Margin of the alert input

$alert-wp-input-padding 0 8px

Padding on the alert input

$alert-wp-input-border-width 2px

Border width of the alert input

$alert-wp-input-border-style $alert-wp-border-style

Border style of the alert input

$alert-wp-input-border-color $input-wp-border-color

Border color of the alert input

$alert-wp-input-border-color-focused color($colors-wp, primary)

Border color of the alert input when focused

$alert-wp-input-line-height 3rem

Line height of the alert input

$alert-wp-input-text-color #000

Color of the text in the alert input

$alert-wp-button-padding 5px

Padding of the alert button

$alert-wp-button-width 49.5%

Width of the alert button

$alert-wp-button-border-radius 0

Border radius of the alert button

$alert-wp-button-font-weight 400

Font weight of the alert button

$alert-wp-button-text-color #000

Color of the text in the alert button

$alert-wp-button-background #b8b8b8

Background color of the alert button

$alert-wp-button-background-activated color-shade($alert-wp-button-background)

Background color of the activated alert button

$alert-wp-button-margin-right 1%

Margin right of the alert button

$alert-wp-button-group-padding 20px 22px 20px 22px

Padding of the alert button group

$alert-wp-button-group-justify-content flex-end

Justify content of the alert button group

$alert-wp-button-group-flex-wrap wrap-reverse

Flex wrap of the alert button group

$alert-wp-button-group-vertical-width 100%

Vertical width of the vertical alert button group

$alert-wp-button-group-vertical-margin-top 5px

Margin top of the vertical alert button group

$alert-wp-radio-background color($colors-wp, primary)

Background color of the radio alert

$alert-wp-radio-border-color $input-wp-border-color

Border color of the radio alert

$alert-wp-radio-label-padding 13px 26px

Padding of the label for the radio alert

$alert-wp-radio-label-text-color-checked $alert-wp-button-text-color

Text color of the label for the checked radio alert

$alert-wp-radio-top 0

Top of the radio alert

$alert-wp-radio-left 13px

Left of the radio alert

$alert-wp-radio-width 16px

Width of the radio alert

$alert-wp-radio-height 16px

Height of the radio alert

$alert-wp-radio-border-width 2px

Border width of the radio alert

$alert-wp-radio-border-style solid

Border style of the radio alert

$alert-wp-radio-border-radius 50%

Border radius of the radio alert

$alert-wp-radio-border-color $input-wp-border-color

Border color of the radio alert

$alert-wp-radio-icon-top 2px

Top of the icon in the radio alert

$alert-wp-radio-icon-left 2px

Left of the icon in the radio alert

$alert-wp-radio-icon-width 8px

Width of the icon in the radio alert

$alert-wp-radio-icon-height 8px

Height of the icon in the radio alert

$alert-wp-radio-icon-border-radius $alert-wp-radio-border-radius

Border radius of the icon in the radio alert

$alert-wp-checkbox-label-padding 13px 26px

Padding of the label for the checkbox in the alert

$alert-wp-checkbox-label-text-color-checked initial

Text color of the label for the checked checkbox in the alert

$alert-wp-checkbox-top 0

Top of the checkbox in the alert

$alert-wp-checkbox-left 13px

Left of the checkbox in the alert

$alert-wp-checkbox-width 16px

Width of the checkbox in the alert

$alert-wp-checkbox-height 16px

Height of the checkbox in the alert

$alert-wp-checkbox-border-width 2px

Border width of the checkbox in the alert

$alert-wp-checkbox-border-style solid

Border style of the checkbox in the alert

$alert-wp-checkbox-border-radius 0

Border radius of the checkbox in the alert

$alert-wp-checkbox-border-color $input-wp-border-color

Border color of the checkbox in the alert

$alert-wp-checkbox-background-off transparent

Background color of the checkbox in the alert when off

$alert-wp-checkbox-background-on color($colors-wp, primary)

Background color of the checkbox in the alert when on

$alert-wp-checkbox-icon-top -2px

Top of the icon in the checkbox alert

$alert-wp-checkbox-icon-left 3px

Left of the icon in the checkbox alert

$alert-wp-checkbox-icon-width 6px

Width of the icon in the checkbox alert

$alert-wp-checkbox-icon-height 12px

Height of the icon in the checkbox alert

$alert-wp-checkbox-icon-border-width 1px

Border width of the icon in the checkbox alert

$alert-wp-checkbox-icon-border-style solid

Border style of the icon in the checkbox alert

$alert-wp-checkbox-icon-border-color color-contrast($colors-wp, $alert-wp-checkbox-background-on)

Border color of the icon in the checkbox alert

$alert-wp-checkbox-icon-transform rotate(45deg)

Transform of the icon in the checkbox alert

API

Native

General