Guides and Sample Code


macOS Human Interface Guidelines



An alert is a dialog that appears when the system or an app needs to give users an important message about an error condition or warn them about potentially hazardous situations or consequences. An alert that applies to a single document or window is displayed as a sheet.

Alerts interrupt users and must be dismissed before users can return to their task. For the best user experience, it’s essential that you avoid displaying an alert unless it’s absolutely necessary. The guidelines in this section help you determine when to display an alert and, if one is required, how to ensure that it’s useful.

image: ../Art/alert_example_2x.png

As you can see in the Finder alert shown above, an alert contains the following elements:

  • The alert message provides a short, simple summary of the error or condition that summoned the alert.

  • The informative text provides a fuller description of the situation, its consequences, and ways in which users can address it.

  • Buttons for addressing the alert appear at the bottom of the dialog. The rightmost button in the dialog, the action button, confirms the alert message text. The action button is usually, but not always, the default button. (For more information about action and default buttons, see Dismissing Dialogs.)

  • The app icon appears to the left of the text and shows users which app is displaying the alert.

When an alert is necessary, your most important job is to explain the situation clearly and give users a way to handle it.

Avoid using an alert merely to give users information. Users don’t appreciate being interrupted by alerts that are informative, but not actionable. Instead of displaying an alert that merely informs, give users the information in another way, such as in an altered status indicator. 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.

Avoid displaying an alert for common, undoable actions, even when they cause data loss. When users delete Mail messages or throw files away, they don’t need to see an alert that warns them about the loss of data. Because users take these actions with the intention of discarding data (and because these actions are easy to undo), an alert is inappropriate. On the other hand, if the user initiates an uncommon action that can't be undone, such as Secure Empty Trash, it’s appropriate to display an alert in case the user didn’t mean to take the action.

If a situation is worthy of an alert, don’t use any other UI element to display it. It might be tempting to use a different element to display alert information, but it would be very confusing for users. Users are familiar with the standard alert and they’re not likely to take the information in a different element as seriously.

Use the Caution icon in rare cases. It’s possible to display a Caution icon in your alert, badged with your app icon. This type of badged alert is appropriate only if the user is performing a task that might result in the inadvertent and unexpected destruction of data. Don’t use a caution icon for tasks whose only purpose is to overwrite or remove data, such as Save or Empty Trash, because the too-frequent use of the caution icon dilutes its significance.

Write an alert message that describes the alert situation clearly and succinctly. An alert message such as “An error occurred” is mystifying to all users and is likely to annoy experienced users. Be as complete and as specific as possible, without being verbose. When possible, identify the error that occurred, the document or file it occurred in, and why it occurred.

When it’s possible that users are unaware that their action might have negative consequences, it can be appropriate to phrase the alert message as a question. For example, a question such as “Are you sure you want to clear history?” pinpoints the action users took and prompts them to consider the results. However, don’t overuse this type of alert; users tire quickly of being asked if they’re sure they want to do something.

Write informative text that elaborates on the consequences and suggests a solution or alternative. Give as much information as necessary to explain why the user should care about the situation. If it's appropriate, use the informative text to remind users that the action they initiated can't be undone.

Informative text is best when it includes a suggestion for fixing the 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.

Express everything in the user’s vocabulary. An alert is an especially bad place to be cryptic or to use esoteric language, because the arrival of an alert can be very unsettling. Even though you want to be succinct, it’s important that you use clear, simple language and avoid jargon. (For some examples of jargon to avoid, see Terminology and Wording.)

Ensure that the default button name corresponds to the action you describe. In particular, it’s a good idea to avoid using OK for the default button. The meaning of OK can be unclear even in alerts that ask if users are 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”?

Using a more focused button name, such as Erase, Convert, Clear, or Delete, helps make sure that users understand the action they’re taking.