# Alerts

Source: https://developer.apple.com/design/human-interface-guidelines/alerts
Skill: hig-components-dialogs
Snapshot: 2025-02-02

---
<!-- hig-doctor:attribution -->
> **Source**: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/alerts.
> This file is a structured index of that content, snapshot 2025-02-02.
> Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

# Alerts

## Best practices

**Use alerts sparingly.**

**Avoid using an alert merely to provide information.**

**Avoid displaying alerts for common, undoable actions, even when they’re destructive.**

**Avoid showing an alert when your app starts.**

## Anatomy

  * iOS 
  * macOS 
  * tvOS 
  * visionOS 
  * watchOS 

## Content

  * In iOS, iPadOS, macOS, and visionOS, an alert can include a text field.

  * Alerts in macOS and visionOS can include an icon and an accessory view.

  * macOS alerts can add a suppression [checkbox](https://developer.apple.com/design/human-interface-guidelines/toggles#Checkboxes) and a [Help button](https://developer.apple.com/design/human-interface-guidelines/buttons#Help-buttons).

**In all alert copy, be direct, and use a neutral, approachable tone.**

**Write a title that clearly and succinctly describes the situation.**

**Include informative text only if it adds value.**

**Avoid explaining alert buttons.**

**If supported, include a text field only if you need people’s input to resolve the situation.**

## Buttons

**Create succinct, logical button titles.**

**Avoid using OK as the default button title unless the alert is purely informational.**

**Place buttons where people expect.**

**Use the destructive style to identify a button that performs a destructive action people didn’t deliberately choose.**

**If there’s a destructive action, include a Cancel button to give people a clear, safe way to avoid the action.**

**Provide alternative ways to cancel an alert when it makes sense.**

## Platform considerations

### iOS, iPadOS

**Use an action sheet — not an alert — to offer choices related to an intentional action.**

**When possible, avoid displaying an alert that scrolls.**

### macOS

  * Configure repeating alerts to let people suppress subsequent occurrences of the same alert.

  * Append a custom view if it’s necessary to provide additional information (for developer guidance, see [`accessoryView`](https://developer.apple.com/documentation/AppKit/NSAlert/accessoryView)).

  * Include a Help button that opens your help documentation (see [Help buttons](https://developer.apple.com/design/human-interface-guidelines/buttons#Help-buttons)).

**Use a caution symbol sparingly.**

---

<!-- hig-doctor:canonical-footer -->
For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/alerts