UIAlertController
UIAlertController represents a system alert: a title, a message, and some buttons. The alert covers the current UI and disappears only after the user taps one of its buttons. An alert has two styles, chosen at creation: an alert box in the middle of the screen, and a menu that rises from the bottom of the screen.
Each button on the alert is a UIAlertAction. Whichever button the user taps fires a click event; the alert itself has no events.
An alert is a view controller. It has no "show" method of its own; present it with the view controller's presentViewController(). The alert's appearance is decided by the system; the App only provides the text and the buttons.
Note: creation, reading and writing properties, and errors were verified in the acceptance tests in the simulator (iPhone Air, iOS 27.2). What it looks like on screen and what happens after a button is tapped can only be verified by someone actually tapping, and are all not verified in the simulator.
Inheritance: EventTarget → NSObject → UIResponder → UIViewController → UIAlertController
For how to make alert boxes, bottom menus, and alerts with text fields, see the guide Showing alerts and menus.
Constructor
Can't be created with new. new UIAlertController() throws TypeError: Illegal constructor: UIAlertController has no public initializer; use UIAlertController.alertControllerWithTitle(title, { message, preferredStyle }). Create one with the static method below.
Static methods
UIAlertController.alertControllerWithTitle()
Creates an alert with a title, a message, and a style.
Instance properties
Also inherits the properties of UIViewController. The alert's title is the inherited title.
| Property | Description |
|---|---|
message | The message below the title |
preferredStyle read-only | The style: alert box or bottom menu |
severity | The severity |
actions read-only | All buttons added |
preferredAction | The button shown in bold in an alert box |
textFields read-only | All text fields added |
Instance methods
Also inherits the methods of UIViewController. To close the alert from code, use the inherited dismissViewController().
| Method | Description |
|---|---|
addAction() | Adds a button |
addTextField() | Adds a text field; only alert boxes can have them |
Events
The alert has no events of its own. To find out which button the user tapped, listen for click on that button.
| Event | When it fires |
|---|---|
traitchange | Inherited from UIViewController: the appearance traits changed. Not verified in the simulator on an alert |
The view controller dismissal events beforedismiss, dismiss, and dismissattempt never fire on an alert, in either style: the system doesn't let an alert report that it was dismissed. Listening for them doesn't throw; they are treated as custom events and only fire when you dispatch them yourself with dispatchEvent().
The two styles
preferredStyle | Where it appears | Can it have text fields? | Suited to |
|---|---|---|---|
'alert' | The middle of the screen | Yes | Telling the user something; asking the user to confirm; asking the user to type a short piece of text |
'actionSheet' | Rises from the bottom of the screen | No; calling addTextField() throws TypeError | Choosing one of several actions |
The style is given at creation and can't be changed afterward.
When the alert closes
Whichever button on the alert the user taps, the system closes the alert. The App can't make a button "not close when tapped".
- The tapped button fires
clickonce after the alert closes; the other buttons fire nothing. Not verified in the simulator. - A button with no listener can still be tapped; tapping it just closes the alert.
- A disabled button can't be tapped: tapping it doesn't close the alert and fires no event. Not verified in the simulator.
- Closing the alert from code with
dismissViewController()doesn't count as tapping a button; no button fires an event. Not verified in the simulator. - A bottom menu can be closed by tapping outside it. That is the same as tapping the button with the cancel style, and that button fires its event. Not verified in the simulator.
- An alert box can't be closed by tapping outside it. The user has no way to close an alert box with no buttons; only code can close it. Not verified in the simulator.
- After the alert closes, the text fields in
textFieldsare still there, and theirtextis what the user typed.
Examples
Asking whether to delete
Starting from a blank App, put a button on the view controller. Tapping it shows an alert box asking the user whether to delete.
application.addEventListener('sceneconnect', (e) => {
const win = new UIWindow(e.scene);
const page = new UIViewController();
page.view.backgroundColor = 'systemBackground';
win.rootViewController = page;
win.makeKeyAndVisible();
const button = UIButton.buttonWithType('system');
button.setTitle('Delete photo', { forState: ['normal'] });
button.frame = new CGRect(40, 120, 200, 44);
page.view.addSubview(button);
button.addEventListener('click', () => {
const alert = UIAlertController.alertControllerWithTitle('Delete this photo?', {
message: 'This can\'t be undone.',
preferredStyle: 'alert',
});
const cancel = UIAlertAction.actionWithTitle('Cancel', { style: 'cancel' });
const remove = UIAlertAction.actionWithTitle('Delete', { style: 'destructive' });
remove.addEventListener('click', () => {
console.log('Photo deleted');
});
alert.addAction(cancel);
alert.addAction(remove);
page.presentViewController(alert, { animated: true });
});
});Effect (not verified in the simulator)
- Near the top left of the view controller is a button with blue text, "Delete photo".
- Tapping it shows an alert box in the middle of the screen, titled "Delete this photo?", with a line of message below it and two buttons at the bottom: "Cancel" and a red "Delete".
- Tapping "Delete" closes the alert box and the console logs
Photo deleted. - Tapping "Cancel" closes the alert box and the console logs nothing.
For more patterns, see the guide Showing alerts and menus.
Corresponding iOS API
| ObjC | JS |
|---|---|
[UIAlertController alertControllerWithTitle:@"Title" message:@"Message" preferredStyle:UIAlertControllerStyleAlert] | UIAlertController.alertControllerWithTitle('Title', { message: 'Message', preferredStyle: 'alert' }) |
[UIAlertAction actionWithTitle:@"OK" style:UIAlertActionStyleDefault handler:^(UIAlertAction *a) { … }] | const a = UIAlertAction.actionWithTitle('OK', { style: 'default' });a.addEventListener('click', () => { … }) |
[alert addAction:action] | alert.addAction(action) |
[alert addTextFieldWithConfigurationHandler:^(UITextField *f) { f.placeholder = @"Name"; }] | const f = alert.addTextField();f.placeholder = 'Name' |
alert.textFields.firstObject.text | alert.textFields[0].text |
alert.preferredAction = action | alert.preferredAction = action |
action.enabled = NO | action.isEnabled = false |
[self presentViewController:alert animated:YES completion:nil] | page.presentViewController(alert, { animated: true }) |
See also
- Showing alerts and menus: showing a one-line message, waiting for the user to choose, entering text, disabling buttons
UIAlertAction: the buttons on an alertUIViewController: the alert's parent class. Presenting, dismissing, and who presented whomUITextField: the type of the text fields in an alertUIActivityViewController: the system share sheet, another system view controller in the same group- Enums: string values of enums, and what happens when one is wrong