Notifications

A notification gives people timely, high-value information they can understand at a glance.

Before you can send any notifications to people, you have to get their consent (for developer guidance, see Asking permission to use notifications). After agreeing, people generally use settings to specify the styles of notification they want to receive, and to specify delivery times for notifications that have different levels of urgency. To learn more about the ways people can customize the notification experience, see Managing notifications.

Anatomy

Depending on the platform, a notification can use various styles, such as:

  • A banner on a Lock Screen, Home Screen, or desktop
  • A badge on an app icon
  • An item in Notification Center

In addition, a notification related to direct communication — like a phone call or message — can provide an interface that’s distinct from noncommunication notifications, featuring prominent contact images (or avatars) and group names instead of the app icon.

Best practices

Provide concise, informative notifications. People enable notifications to get quick updates, so focus on providing valuable information succinctly.

Avoid sending multiple notifications for the same thing, even if someone hasn’t responded. People attend to notifications at their convenience. If you send multiple notifications for the same thing, you fill up Notification Center, and people may turn off all notifications from your app.

Avoid sending a notification that tells people to perform specific tasks within your app. If it makes sense to enable simple tasks that people can perform without opening your app, you can provide notification actions. Otherwise, avoid telling people what to do because it’s hard for people to remember such instructions after they dismiss the notification.

Use an alert — not a notification — to display an error message. People are familiar with both alerts and notifications, so you don’t want to cause confusion by using the wrong component. For guidance, see Alerts.

Handle notifications gracefully when your app is in the foreground. Your app’s notifications don’t appear onscreen when your app is in the front, but your app still receives the information. In this scenario, present the information in a way that’s discoverable but not distracting or invasive, such as incrementing a badge or subtly inserting new data into the current view. For example, when a new message arrives in a mailbox that people are currently viewing, Mail simply adds it to the list of unread messages because sending a notification about it would be unnecessary and distracting.

Avoid including sensitive, personal, or confidential information in a notification. You can’t predict what people will be doing when they receive a notification, so it’s essential to avoid including private information that could be visible to others on the device screen.

Content

When a notification includes a title, the system displays it at the top where it’s most visible. In a notification related to direct communication, the system automatically displays the sender’s name in the title area; in a noncommunication notification, the system displays your app name if you don’t provide a title.

Create a short title if it provides context for the notification content. Prefer brief titles that people can read at a glance, especially on Apple Watch, where space is limited. When possible, take advantage of the prominent notification title area to provide useful information, like a headline, event name, or email subject. If you can only provide a generic title for a noncommunication notification — like New Document — it can be better to let the system display your app name instead. Use title-style capitalization and no ending punctuation.

Write succinct, easy-to-read notification content. Use complete sentences, sentence case, and proper punctuation, and don’t truncate your message — the system does this automatically when necessary.

Provide generically descriptive text to display when notification previews aren’t available. In Settings, people can choose to hide notification previews for all apps. In this situation, the system shows only your app icon and the default title Notification. To give people sufficient context to know whether they want to view the full notification, write body text that succinctly describes the notification content without revealing too many details, like “Friend request,” “New comment,” “Reminder,” or “Shipment” (for developer guidance, see hiddenPreviewsBodyPlaceholder). Use sentence-style capitalization for this text.

Avoid including your app name or icon. The system automatically displays a large version of your app icon at the leading edge of each notification; in a communication notification, the system displays the sender’s contact image badged with a small version of your icon.

Consider providing a sound to supplement your notifications. Sound can be a great way to distinguish your app’s notifications and get someone’s attention when they’re not looking at the screen. You can create a custom sound that coordinates with the style of your app or use a system-provided alert sound. If you use a custom sound, make sure it’s short, distinctive, and professionally produced. A notification sound can enhance the user experience, but don’t rely on it to communicate important information, because people may not hear it. Although people can also enable a vibration that accompanies alert sounds, you can’t enable such a vibration programmatically. For developer guidance, see UNNotificationSound.

Notification actions

A notification can present a customizable detail view that contains up to four buttons people use to perform actions without opening your app. For example, a Calendar event notification provides a Snooze button that postpones the event’s alarm for a few minutes. For developer guidance, see Handling notifications and notification-related actions.

Provide beneficial actions that make sense in the context of your notification. Prefer actions that let people perform common, time-saving tasks that eliminate the need to open your app. For each button, use a short, title-case term or phrase that clearly describes the result of the action. Don’t include your app name or any extraneous information in the button label, keep the text brief to avoid truncation, and take localization into account as you write it.

Avoid providing an action that merely opens your app. When people tap a notification or its preview, they expect your app to open the relevant screen, so presenting an action button that does the same thing clutters the detail view and can be confusing.

Prefer nondestructive actions. If you must provide a destructive action, make sure people have enough context to avoid unintended consequences. The system gives a distinct appearance to the actions you identify as destructive.

Provide a simple, recognizable interface icon for each notification action. An interface icon reinforces an action’s meaning, helping people instantly understand what it does. The system displays your interface icon on the trailing side of the action title. When you use SF Symbols, you can choose an existing symbol that represents your command or edit a related symbol to create a custom icon.

Badging

A badge is a small, filled oval containing a number that can appear on an app icon to indicate the number of unread notifications that are available. After people address unread notifications, the badge disappears from the app icon, reappearing when new notifications arrive. People can choose whether to allow an app to display badges in their notification settings.

Use a badge only to show people how many unread notifications they have. Don’t use a badge to convey numeric information that isn’t related to notifications, such as weather-related data, dates and times, stock prices, or game scores.

Make sure badging isn’t the only method you use to communicate essential information. People can turn off badging for your app, so if you rely on it to show people when there’s important information, people can miss the message. Always make sure that you make important information easy for people to find as soon as they open your app.

Keep badges up to date. Update your app’s badge as soon as people open the corresponding notifications. You don’t want people to think there are new notifications available, only to find that they’ve already viewed them all. Note that reducing a badge’s count to zero removes all related notifications from Notification Center.

Avoid creating a custom image or component that mimics the appearance or behavior of a badge. People can turn off notification badges if they choose, and will become frustrated if they have done so and then see what appears to be a badge.

Platform considerations

No additional considerations for iOS, iPadOS, macOS, or tvOS.

watchOS

On Apple Watch, notifications occur in two stages: short look and long look. People can also view notifications in Notification Center.

You can help people have a great notification experience by designing app-specific assets and actions that are relevant on Apple Watch. If your watchOS app has an iPhone companion that supports notifications, watchOS can automatically provide default short-look and long-look interfaces if necessary.

Short looks

A short look appears when the wearer’s wrist is raised and disappears when it’s lowered.

A screenshot of the activity app showing all three rings closed and text that says goal achieved.

Avoid using a short look as the only way to communicate important information. A short look appears only briefly, giving people just enough time to see what the notification is about and which app sent it. If your notification information is critical, make sure you deliver it in other ways, too.

Keep privacy in mind. Short looks are intended to be discreet, so it’s important to provide only basic information. Avoid including potentially sensitive information in the notification’s title.

Long looks

Long looks provide more detail about a notification. If necessary, people can swipe vertically or use the Digital Crown to scroll a long look. After viewing a long look, people can dismiss it by tapping it or simply by lowering their wrist.

A screenshot of a Calendar notification for an invitation from Lexi Torres for an event called Let's Celebrate! The screenshot extends below the device frame to display the event's date and location, in addition to Accept, Maybe, Decline, and Dismiss buttons.

A custom long-look interface can be static or dynamic. The static interface lets you display a notification’s message along with additional static text and images. The dynamic interface gives you access to the notification’s full content and offers more options for configuring the appearance of the interface.

You can customize the content area for both static and dynamic long looks, but you can’t change the overall structure of the interface. The system-defined structure includes a *sash *at the top of the interface and a Dismiss button at the bottom, below all custom buttons.

Consider using a rich, custom long-look notification to let people get the information they need without launching your app. You can use SwiftUI to create engaging, interruptible animations; alternatively, you can use SpriteKit or SceneKit.

At the minimum, provide a static interface; prefer providing a dynamic interface too. The system defaults to the static interface when the dynamic interface is unavailable, such as when there is no network or the iPhone companion app is unreachable. Be sure to create the resources for your static interface in advance and package them with your app.

Choose a background appearance for the sash. The system-provided sash, at the top of the long-look interface, displays your app icon and name. You can customize the sash’s color or give it a blurred appearance. If you display a photo at the top of the content area, you’ll probably want to use the blurred sash, which has a light, translucent appearance that gives the illusion of overlapping the image.

Choose a background color for the content area. By default, the long look’s background is transparent. If you want to match the background color of other system notifications, use white with 18% opacity; otherwise, you can use a custom color, such as a color within your brand’s palette.

Provide up to four custom actions below the content area. For each long look, the system uses the notification’s type to determine which of your custom actions to display as buttons in the notification UI. In addition, the system always displays a Dismiss button at the bottom of the long-look interface, below all custom buttons. If your watchOS app has an iPhone companion that supports notifications, the system shares the actionable notification types already registered by your iPhone app and uses them to configure your custom action buttons.

Supported platforms