An alert appears when the system or an app needs to provide important information about an error condition or warn the user about a potentially hazardous situation or consequence. An alert is modal within an app unless it pertains to a single document or window, in which case it’s displayed as a sheet.

An alert may include the following elements:

Element Description
Message Provides a short summary of the error or condition that summoned the alert. All alerts include a message.
Informative text Provides a fuller description of the situation, its consequences, and ways in which users can address it. Informative text is optional but encouraged.
Response buttons An alert can include up to three buttons, one of which can be set as the default button, for canceling the alert or taking action.
Icon The system automatically shows your app icon on an alert. Custom icons are also supported. A caution symbol can be appended to the icon in alerts that require extra attention.
Suppression checkbox Repeating alerts can be configured to let the user suppress subsequent occurrences of the same alert.
Accessory view If your app calls for it, a custom view can be appended to an alert to provide additional information.
Help button If your app offers Help documentation, you can include a Help button in your alert that takes the user to the documentation.

Minimize alerts. Alerts disrupt the user experience and should only be used in important situations like confirming purchases and destructive actions (such as deletions), or notifying people about problems. The infrequency of alerts helps ensure that people take them seriously. Ensure that each alert offers critical information and useful choices.

Avoid using an alert merely to provide information. Users don’t appreciate being interrupted by alerts that are informative, but not actionable. Instead of displaying an informational alert, consider other ways of presenting the information. For example, when a Mail server connection has been lost, Mail displays a warning indicator in the sidebar. Users can click the warning indicator if they want more information about the situation.

Use standard alerts. Users are familiar with the standard, system-provided alert style and understand its importance. Alert information presented in custom or nonstandard ways can be confusing and is less likely to be taken seriously.

Avoid displaying alerts for common, undoable actions, even when they’re destructive. Users don’t need to be alerted to potential data loss every time they delete an email or file. Actions like these are taken with the intention of discarding data and can be undone. On the other hand, an uncommon destructive action that can’t be undone should produce an alert in case the user didn’t intend to take the action.

Use the caution symbol sparingly. Over use of the caution symbol in an alert diminishes its significance. Use the symbol only when extra attention is truly required, such as to confirm an action that might result in inadvertent or unexpected loss of data. Don’t use the icon for tasks whose only purpose is to overwrite or remove data, such as a save or empty trash.

Consider including an option to suppress future alerts of the same type. Users appreciate the ability to prevent future alerts from appearing for the same reason. For example, the user may be comfortable clearing their history without seeing repeated warnings. If you allow alert suppression, be sure to provide a way to reenable the alerts again, such as via a Show Warnings option in the View menu.

For developer guidance, see NSAlert.

Alert Text

Provide a message that describes the situation clearly and succinctly. A message like “An error occurred.” is mystifying and likely to annoy people. Be complete and specific, without being verbose. When possible, identify the error that occurred, the document or file it occurred in, and why it occurred.

Consider phrasing a message as a question when the default action has negative consequences. For example, a question such as “Are you sure you want to clear the history?” pinpoints the action that produced the alert and encourages the user to consider the results. Don’t overuse this type of alert, however. Users tire quickly of being asked if they’re sure they want to do something.

Supplement your alert message with informative text. Use informative text to expand on the message text by elaborating on consequences and suggesting a solution or alternative. Give as much information as necessary to explain why the user should care about the situation. When appropriate, remind users when an action can't be undone. Whenever possible, suggest how to fix a problem. For example, when the Finder can’t use the user’s input to rename a file, it tells them to try using fewer characters or avoid including punctuation marks.

Avoid sounding accusatory, judgmental, or insulting. People know that alerts notify them about problems and dangerous situations. As long as you use a friendly tone, it’s better to be negative and direct than positive and oblique. Avoid pronouns such as you, your, me, and my, which are sometimes interpreted as insulting or patronizing.

Avoid explaining alert buttons. If your alert text and button titles are clear, there should be no need to explain what the buttons do. In rare cases where you must provide guidance, preserve capitalization when referencing buttons, and don’t enclose button titles in quotes.

Alert Buttons

Generally, use two-button alerts. Two-button alerts provide an easy choice between two alternatives. Single-button alerts inform, but give no control over the situation. Alerts with three or more buttons create complexity.

Give alert buttons succinct, logical titles. The best button titles consist of one or two words that describe the result of clicking the button. As with all button titles, use title-style capitalization and no ending punctuation. To the extent possible, use verbs and verb phrases that relate directly to the alert title and message—for example, View All, Reply, or Ignore. Use OK for simple acceptance. Avoid using Yes and No.

Ensure that the default button title reflects the action the button performs. Avoid using OK for the default button unless the alert is purely informational. The meaning of OK can be unclear even in alerts that ask if the user is sure they want to do something. For example, does OK mean “OK, I want to complete the action” or “OK, I now understand the negative results my action would have caused”? A specific button title like Erase, Convert, Clear, or Delete helps the user understand the action they’re taking.

Place buttons where people expect them. In general, the button people are most likely to choose should be on the right. The default button should always be on the right. Cancel buttons are typically on the left.

Label cancellation buttons appropriately. A button that cancels an alert’s action should always be labeled Cancel.

Include a Cancel button when there’s a destructive button. A Cancel button provides a clear, safe way to opt out of a destructive action. Consider making the Cancel button the default button too, requiring the user to intentionally click a button to continue with the destructive action.

Allow the Esc (Escape) key and Command-Period (.) keyboard shortcut to cancel alerts. Pressing Esc or Command-Period while an alert is visible should produce the same effect as clicking the Cancel button—that is, the alert is dismissed without performing any action. If your alert doesn’t have a Cancel button, consider implementing a cancel action in your code that runs when Esc or Command-Period is pressed.

Consider offering time-saving keyboard shortcuts for all buttons. For example, you could let people activate a Print button by pressing the P key, or a Don't Save button by pressing the D or Delete key.