Guides and Sample Code


macOS Human Interface Guidelines

On This Page

App Extensions

App extensions increase the reach of your app, giving users access to focused parts of its functionality while they use other apps. For example, while viewing websites in Safari, people can use your Share extension to post an image or an article to your social website. Or while using the Finder, people can use your Finder Sync extension to choose documents that you synchronize with a remote data source. (In these scenarios, Safari and the Finder are called host apps because they give users access to extensions.)

You deliver an app extension inside an app that you submit to the App Store (an app that contains extensions is called a containing app). After enabling the extension in your containing app, people can use it to perform a quick task while they’re using other apps. For example, while reading about a product in an email message, people might use your Action extension to add the product to a shopping list without having to leave Mail.

Table 48-1 lists the types of app extensions you can create.

Table 48-1Types of app extensions

App extension type

People use the extension to…

Today widget

Get a quick update or perform a quick task in the Today view of Notification Center


Post to a website or share content with others


Manipulate or view content within the context of another app

Finder Sync

Get information about file sync status within the Finder

The following guidelines apply to app extensions of all types; for guidance that’s specific to a particular type of app extension, see the sections below. (To learn how to develop, debug, and distribute an extension, see App Extension Programming Guide.)

Enable a single task. An app extension is not a mini version of your app. Instead, an extension performs a narrowly scoped task in the context of the user’s larger goal. And because users typically perform the task within the app extension's dedicated view, the extension user experience is a lot like the experience of other modal tasks.

Keep user interactions limited and streamlined. The best app extensions let people perform the task in just a few clicks or gestures so that they can return to their earlier context as soon as possible. For example, a Share extension might let people post an image with a single click.

Incorporate the name of your containing app into the name of each extension it provides. Although multiple extensions in one containing app should each have a unique name, you want to make sure that users understand the relationship between your extensions and your app. People encounter extensions in many different contexts, and they’re unlikely to trust an extension if they don’t recognize it.

In most cases, use the icon of the containing app. Displaying a familiar icon is another way an extension can gain users’s trust.

Avoid displaying a modal view on top of an extension. Many extensions are displayed within a modal view by default, and it’s best to avoid layering modal views. Although there are cases where users might see an alert on top of an extension, avoid designing an extension workflow that requires a modal view.

Today Widgets

People view Today widgets in the Today area of Notification Center. Because people configure the Today area so that it displays the information they value most, it works well to approach the design of your widget with the goal of earning a place among the user’s most important items.

image: ../Art/today_widgets_2x.png

Design an appearance that looks at home in Notification Center. Notification Center uses the vibrant dark appearance, and your widget content should, too. Also, when you use the default margins provided by Notification Center, your Today widget gives users a consistent experience. In general, focus on drawing your content and not on drawing backgrounds or custom materials.

In general, use the system font in the appropriate color to display text. Specifically, choose the color that reflects the semantic meaning of your text, such as labelColor (for primary text) and secondaryLabelColor (for less important text). When you use the system-provided colors, your text automatically gets the appropriate vibrancy (to learn more about the system-provided colors, see Use System Colors to Integrate with System Appearances).

Provide a Notification Center experience. People visit Notification Center to get brief updates or to perform a very simple task, so it’s best when your Today widget displays the right amount of information and limits interactivity. Specifically:

  • Avoid making users vertically shift the view to see all the information in your Today widget. A widget can expand vertically to show more information, but it’s not a good experience when a widget’s height takes up too much of Notification Center, because it interferes with scrolling to see other Today widgets.

  • Avoid making users horizontally shift the view, because it might interfere with the dismiss Notification Center gesture. If you need a table view in your widget, be sure to use a fixed-size table view (that is, a table view that doesn’t include a scroll view).

  • Help users perform a task with as little interaction as possible. The keyboard is available to macOS widgets, but you don’t want to encourage users to do a lot of typing.

  • Optimize performance so that people get useful information immediately. It's a good idea to cache information locally so that you can display recent information while you get updates.

If appropriate, let people open your app from your Today widget. Because your Today widget provides a narrowly focused experience, it can work well to direct people to your app for more information or functionality. It’s not a good idea to provide an “Open App” button, so one solution is to make your entire Today widget clickable. Or you might let users click an appropriate UI object within the widget so that it opens your app to a view that’s focused on that object. For example, the Calendar widget shows today’s events; if users want to get more information about an event, they click the event in the widget to view it in the Calendar app.

Share Extensions

People access Share extensions in the Share menu—which users reveal by clicking the Share button or choosing the Share item in a contextual menu—or in the Social area in Notification Center. In the Share menu (shown here in Safari), people can use the More button to manage the Share extensions that are displayed in the menu shown here.

image: ../Art/share_extensions_2x.png

A Share extension typically takes as input the user’s current context or currently selected content. While reading an article in Safari, for example, a user might click the Share button and use a Share extension to post the webpage to a sharing website. Or while editing a document, a user might select a passage, open the contextual menu, and choose the Messages extension to share the selection with a contact.

As much as possible, use the system-provided UI in a Share extension. The system-provided compose view controller gives users a consistent experience and automatically supports common tasks, such as previewing and validating standard items, synchronizing content and view animation, and configuring a post. To learn more about using the system-provided compose view controller, see Share in App Extension Programming Guide.

Consider displaying the progress of a lengthy upload in a Share extension’s containing app. People expect to return to their previous context immediately after tapping an extension’s Post or Share button, even when the shared content is large. You need to make progress updates available, but people don’t want to get a notification every time an upload completes, and there’s no way to programmatically relaunch an extension. In this scenario, it can work well to display the progress of the upload in the containing app, which can handle the task in the background and send a notification if there’s a problem.

Action Extensions

People can choose an Action extension in a few different ways. Specifically, people can:

  • Open the Share menu and choose the extension

  • Click the extension’s toolbar button

  • Hold the pointer over selected content or an attachment, click the button that appears, and choose the extension in the menu (shown here in TextEdit)

image: ../Art/action_extension_menu_2x.png

There are two types of Action extensions:

  • Viewer. A viewer Action extension displays the current content in a custom way, but doesn’t modify it.

  • Editor. An editor Action extension can let users edit the current content. After users confirm their edits, the extension replaces the original content in the host app with the edited version. The system-provided Markup extension is an example of an editor Action extension.

If appropriate, display your Action extension UI within the context of the host app. For example, the built-in Markup action extension lets the user edit the image without leaving the primary app (shown here in TextEdit).

image: ../Art/action_extension_ui_2x.png

Use a monochromatic version of the app icon for an Action extension. (In contrast, a Share extension uses its containing app’s full-color app icon.) To create an icon for an Action extension, you might start by creating a stencil version of your app icon. If necessary, simplify the design by focusing on the elements that make your icon unique.

If you provide multiple Action extensions in your containing app, it can work well to create a family of icons for them. Be sure to make every icon in the family look related to the containing app’s icon.

Finder Sync Extensions

Typically, Finder Sync extensions are provided by apps that synchronize the contents of a local folder with a remote data source. People use a Finder Sync extension to check on the sync status of their files and manage folder contents within a Finder window.

A Finder Sync extension provides badges that indicate the sync status of each item, and contextual menus that contain folder-management menu items, such as Copy and Open. In addition, a Finder Sync extension can provide custom buttons for the Finder toolbar that can perform global actions, such as opening a monitored folder or forcing a sync operation.

Use badges sparingly. For example, it can be better to show users which files are not synced if the alternative is to clutter the Finder window by badging every file with your “synced” badge.