Action Extensions

An action extension lets people initiate content-specific tasks—such as editing an inline image, adding a bookmark, or displaying selected text in another language—without leaving the current context. You can also use an action extension to provide Quick Actions in the Finder and the Touch Bar.

People can access an action extension by positioning the pointer over certain types of embedded content. For example, hovering over an image dragged into a Mail compose window reveals an action disclosure button, as shown below. People may also access action extensions in the menu revealed by the Share toolbar button or the extension's custom toolbar button.

Screenshot of a Mail compose window that contains a photo in the content area. A contextual menu is displayed on top of the photo, and lists the Markup action extension and a More… item.

When you use an action extension to support a Quick Action, people can enable the action in the Touch Bar or the Finder by configuring Keyboard or Extensions settings in System Preferences.

Screenshot of the Extensions pane in System Preferences that shows Finder Quick Actions enabled for Rotate, Markup, Create PDF, and Trim.

There are two types of action extensions:

  • Viewer: Provides a custom way of viewing—but not modifying—the current content. An action extension that displays a translation of selected text is an example of a viewer action extension.

  • Editor: Enables editing of the current content. After edits are confirmed by the user, the extension replaces the original content with the edited version. The system-provided Markup extension is an example of an editor action extension.

The system offers only the action extensions that can work with the current content type. For example, action extensions that support text aren’t shown when the current content is a video.

Expose a single, focused task. An action extension isn’t a mini-app. It performs a narrowly scoped task related to the current context. For example, the Markup extension lets people edit the selected image, but doesn't let them duplicate, rename, or move the image.

Don’t assume your action extension is available. Users can enable and disable action extensions in the Extensions system preference pane.

Screenshot of a photo within the editing panel of the Markup extension. The Mail compose window is shown beneath the panel.

Provide an interface only when necessary. For example, the Markup action extension lets the user add text to, draw on, or sign an image without leaving the app. The interface you provide should be recognizable and feel like a natural extension of your app.

Streamline and limit interaction. The best extensions let people perform a task in just a few steps.

Use a template image version of your app icon to represent your action extension icon. A template image uses a mask to create an icon. To create an action extension icon, 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. Use transparency and antialiasing; don’t include a drop shadow. If your app offers multiple action extensions, create a family of icons that share a common visual element related to your app’s icon.

For developer guidance, see Add Functionality to Finder with Action Extensions.