Alerts

Provide information or give user's a choice

Example Alerts

How alerts work

Tapping any button dismisses the alert. If an action name is associated with the tapped button, Critical Moments triggers that action.

Alert Action Config

An alert has actionType alert and an actionData object with the following keys:

  • title [string, optional]: The title of the alert. May be empty, but you must have a title and/or a message, both can't be omitted.

  • style [sting, optional]: one of "dialog", or "large". Defaults to dialog if omitted. See above for visual examples of each style.

  • message [string, optional]: The message body of the alert. May be empty, but you must have a title and/or a message, both can't be omitted.

  • showOkButton [bool, optional]: If true, show an "OK" button. Defaults to true if omitted. Defaults to no action, but an action can be set with okButtonActionName

    • You should use this property over a custom button with an "OK" string because it follows system conventions for OK buttons: placement in button order, and bold treatment.

    • It will localize using the system standard "OK" string.

  • okButtonActionName [string, optiona]: the name of an action, which is fired when the user taps the okay button. No action is fired if this is omitted.

  • showCancelButton [bool, optional]: If true, show an "Cancel" button which dismisses the alert. Defaults to false if omitted.

    • You should use this property over a custom button with an "Cancel" string because it follows system conventions for Cancel buttons regarding placement in the alert.

    • It will localize using the system standard "Cancel" string.

  • customButtons [array, optional]: an array of custom button objects with the following keys:

    • label [string, required]: the label of the button

    • actionName [string, optional]: the action to fire when the button is tapped

    • style [string, optional]: the style of the alert button. One of "default", "destructive" (red) or "primary" (bold). Only one button can be primary on iOS - the last button you specify as primary (including OK) will get the primary treatment. See above for visual examples. Defaults to "default" if omitted.

Design Considerations

Alerts have more design considerations than you'd expect! Critical Moments is designed to make it easy to comply with the Apple Human Interface guide for alerts.

  • A Title and/or body is required. Neither is not allowed. Both are suggested.

  • You must have at least 1 button: OK, or a custom button. No buttons or a single cancel button are not valid

  • The Apple suggested position and font-weight of the OK and Cancel buttons changes based on platform (phone vs iPad), layout (dialog vs large) and which other buttons are present. Using the options showOkayButton/showCancelButton will ensure these buttons follow platform standards, and is highly recommended over custom buttons with the label "OK"/"Cancel".

  • There is no theme support for alerts, they use the system native alert look

Example Config

The config below from the Sample App generated the alerts in the screenshots above.

"show_notice_alert": {
    "actionType": "alert",
    "actionData": {
        "title": "A simple notice alert",
        "message": "Title, message, okay button. You get the idea!"
    }
},
"show_cancelable_alert": {
    "actionType": "alert",
    "actionData": {
        "title": "A cancelable alert",
        "message": "An alert with a cancel button... not exactly rocket science.\n\nTry both buttons to see what they do.",
        "showCancelButton": true,
        "okButtonActionName": "nested_alert"
    }
},
"custom_button_alert_large": {
    "actionType": "alert",
    "actionData": {
        "title": "Action sheet deep dive",
        "message": "This is an action sheet with several options.\n\nEach can launch a custom action!",
        "showOkButton": false,
        "showCancelButton": true,
        "style": "large",
        "customButtons": [
            {
                "label": "Option 1",
                "actionName": "nested_alert"
            },
            {
                "label": "Option 2",
                "actionName": "nested_alert"
            },
            {
                "label": "Option 3",
                "actionName": "nested_alert"
            },
            {
                "label": "Option 4",
                "actionName": "nested_alert"
            },
            {
                "label": "Scary option",
                "actionName": "nested_alert",
                "style": "destructive"
            }
        ]
    }
},
"custom_button_alert_dialog": {
    "actionType": "alert",
    "actionData": {
        "title": "Lots of options",
        "message": "This is an alert with several buttons of different styles.",
        "showOkButton": false,
        "showCancelButton": true,
        "customButtons": [
            {
                "label": "Normal button",
                "actionName": "nested_alert"
            },
            {
                "label": "Primary button",
                "actionName": "nested_alert",
                "style": "primary"
            },
            {
                "label": "Scary button",
                "actionName": "nested_alert",
                "style": "destructive"
            }
        ]
    }
},

Last updated