iOS Developer Library — Prerelease

Developer

UIKit Framework Reference UIAlertController Class Reference

Options
Deployment Target:

On This Page
Language:

UIAlertController

A UIAlertController object displays an alert message to the user. This class replaces the UIActionSheet and UIAlertView classes for displaying alerts. After configuring the alert controller with the actions and style you want, present it using the presentViewController:animated:completion: method.

In addition to displaying a message to a user, you can associate actions with your alert controller to give the user a way to respond. For each action you add using the addAction: method, the alert controller configures a button with the action details. When the user taps that action, the alert controller executes the block you provided when creating the action object. Listing 1 shows how to configure an alert with a single action.

Listing 1Configuring and presenting an alert
  1. UIAlertController* alert = [UIAlertController alertControllerWithTitle:@"My Alert"
  2. message:@"This is an alert."
  3. preferredStyle:UIAlertControllerStyleAlert];
  4. UIAlertAction* defaultAction = [UIAlertAction actionWithTitle:@"OK" style:UIAlertActionStyleDefault
  5. handler:^(UIAlertAction * action) {}];
  6. [alert addAction:defaultAction];
  7. [self presentViewController:alert animated:YES completion:nil];

When configuring an alert with the UIAlertControllerStyleAlert style, you can also add text fields to the alert interface. The alert controller lets you provide a block for configuring your text fields prior to display. The alert controller maintains a reference to each text field so that you can access its value later.

Subclassing Notes

The UIAlertController class is intended to be used as-is and does not support subclassing. The view hierarchy for this class is private and must not be modified.

  • Creates and returns a view controller for displaying an alert to the user.

    Declaration

    Swift

    convenience init(title title: String?, message message: String?, preferredStyle preferredStyle: UIAlertControllerStyle)

    Objective-C

    + (instancetype _Nonnull)alertControllerWithTitle:(NSString * _Nullable)title message:(NSString * _Nullable)message preferredStyle:(UIAlertControllerStyle)preferredStyle

    Parameters

    title

    The title of the alert. Use this string to get the user’s attention and communicate the reason for the alert.

    message

    Descriptive text that provides additional details about the reason for the alert.

    preferredStyle

    The style to use when presenting the alert controller. Use this parameter to configure the alert controller as an action sheet or as a modal alert.

    Return Value

    An initialized alert controller object.

    Discussion

    After creating the alert controller, configure any actions that you want the user to be able to perform by calling the addAction: method one or more times. When specifying a preferred style of UIAlertControllerStyleAlert, you may also configure one or more text fields to display in addition to the actions.

    Availability

    Available in iOS 8.0 and later.

  • The title of the alert.

    Declaration

    Swift

    var title: String?

    Objective-C

    @property(nonatomic, copy, nullable) NSString *title

    Discussion

    The title string is displayed prominently in the alert or action sheet. You should use this string to get the user’s attention and communicate the reason for displaying the alert.

    Availability

    Available in iOS 8.0 and later.

  • Descriptive text that provides more details about the reason for the alert.

    Declaration

    Swift

    var message: String?

    Objective-C

    @property(nonatomic, copy, nullable) NSString *message

    Discussion

    The message string is displayed below the title string and is less prominent. Use this string to provide additional context about the reason for the alert or about the actions that the user might take.

    Availability

    Available in iOS 8.0 and later.

  • The style of the alert controller. (read-only)

    Declaration

    Swift

    var preferredStyle: UIAlertControllerStyle { get }

    Objective-C

    @property(nonatomic, readonly) UIAlertControllerStyle preferredStyle

    Discussion

    The value of this property is set to the value you specified in the alertControllerWithTitle:message:preferredStyle: method. This value determines how the alert is displayed onscreen.

    Availability

    Available in iOS 8.0 and later.

  • Attaches an action object to the alert or action sheet.

    Declaration

    Swift

    func addAction(_ action: UIAlertAction)

    Objective-C

    - (void)addAction:(UIAlertAction * _Nonnull)action

    Parameters

    action

    The action object to display as part of the alert. Actions are displayed as buttons in the alert. The action object provides the button text and the action to be performed when that button is tapped.

    Discussion

    If your alert has multiple actions, the order in which you add those actions determines their order in the resulting alert or action sheet.

    Availability

    Available in iOS 8.0 and later.

  • The actions that the user can take in response to the alert or action sheet. (read-only)

    Declaration

    Swift

    var actions: [UIAlertAction] { get }

    Objective-C

    @property(nonatomic, readonly, nonnull) NSArray <UIAlertAction *> *actions

    Discussion

    The actions are in the order in which you added them to the alert controller. This order also corresponds to the order in which they are displayed in the alert or action sheet. The second action in the array is displayed below the first, the third is displayed below the second, and so on.

    Availability

    Available in iOS 8.0 and later.

  • Adds a text field to an alert.

    Declaration

    Swift

    func addTextFieldWithConfigurationHandler(_ configurationHandler: ((UITextField) -> Void)?)

    Objective-C

    - (void)addTextFieldWithConfigurationHandler:(void (^ _Nullable)(UITextField * _Nonnull textField))configurationHandler

    Parameters

    configurationHandler

    A block for configuring the text field prior to displaying the alert. This block has no return value and takes a single parameter corresponding to the text field object. Use that parameter to change the text field properties.

    Discussion

    Calling this method adds an editable text field to the alert. You can call this method more than once to add additional text fields. The text fields are stacked in the resulting alert.

    You can add a text field only if the preferredStyle property is set to UIAlertControllerStyleAlert.

    Availability

    Available in iOS 8.0 and later.

  • The array of text fields displayed by the alert. (read-only)

    Declaration

    Swift

    var textFields: [UITextField]? { get }

    Objective-C

    @property(nonatomic, readonly, nullable) NSArray <UITextField *> *textFields

    Discussion

    Use this property to access the text fields displayed by the alert. The text fields are in the order in which you added them to the alert controller. This order also corresponds to the order in which they are displayed in the alert.

    Availability

    Available in iOS 8.0 and later.

  • Constants indicating the type of alert to display.

    Declaration

    Swift

    enum UIAlertControllerStyle : Int { case ActionSheet case Alert }

    Objective-C

    typedef enum UIAlertControllerStyle: NSInteger { UIAlertControllerStyleActionSheet = 0, UIAlertControllerStyleAlert } UIAlertControllerStyle;

    Constants

    • ActionSheet

      UIAlertControllerStyleActionSheet

      An action sheet displayed in the context of the view controller that presented it.

      Use an action sheet to present the user with a set of alternatives for how to proceed with a given task. You can also use this style to prompt the user to confirm a potentially dangerous action.

      Available in iOS 8.0 and later.

    • Alert

      UIAlertControllerStyleAlert

      An alert displayed modally for the app.

      Available in iOS 8.0 and later.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.