Guides and Sample Code

Developer

macOS Human Interface Guidelines

iBooks
On This Page

System-Provided Images

Throughout macOS, you can see quantities of small, monochromatic images in toolbar controls and scope buttons. Some of the most familiar of these images, such as go back, set object view to icons, list, columns, or Cover Flow, view Action menu, view in Quick Look, and show path, and are shown here in the Finder toolbar.

image: ../Art/finder_toolbar_2x.png

In addition to these images, many macOS apps display full-color standard images in preferences window toolbars. For example, the toolbar in the Calendar preferences window contains the general, accounts, and advanced images.

image: ../Art/full-color_images_in_toolbar_2x.png

The standard images of the first type (such as the view in Quick Look symbol) are known as template images. A template image is a black and clear image that can be used inside a control (such as a toolbar button). Template images are expected to receive additional processing, such as displaying an inverted variation. For a list of these images, see System-Provided Images for Use in Controls; to learn more about toolbar buttons, see Some Controls Can Be Used in the Window Frame.

Standard images of the second type (such as the general preferences symbol) can be used as standalone icon buttons in a preferences window’s toolbar. Because these images are not template images, they can't be used inside an app window’s toolbar controls (or any other controls). For a list of these images, see System-Provided Images for Use as Toolbar Items.

macOS also provides a handful of standard images that can appear in the window body, such as the invalid data image. For a list of these images, see System-Provided Images for Use as Standalone Buttons.

Every system-provided image has a specific meaning that users know. To avoid confusing users, it is essential that you use each image in accordance with its documented meaning and recommended usage.

When you use standard images correctly in your app, you also benefit from:

  • Shorter development time and less effort spent on creating custom images.

  • Automatic updating of images if appearance changes occur in future operating system updates.

To understand why it’s important to use these images correctly, consider the following hypothetical example. Imagine that the “go forward” image (that is, the right-pointing angle) is changed to look like a capital letter “F.” If you correctly use this image in a control that performs a “go forward” action, the control still makes sense when it uses the new appearance. But if you incorrectly use the image to mean “play,” your play control is suddenly nonsensical and confusing when it displays the “F.”

If you can’t find a system-provided image that has the appropriate meaning for a specific purpose in your app, it’s better to design your own than to misuse a system-provided image. To learn how to design items for a toolbar, see Toolbar Items.

System-Provided Images for Use in Controls

macOS provides many template images intended for use primarily in toolbar controls. Because these images require the presence of a bounding box (which is supplied by the control), they are not as useful for standalone buttons or free-standing toolbar icons. Instead, see System-Provided Images for Use as Standalone Buttons for images you can use as standalone buttons, and see System-Provided Images for Use as Toolbar Items for images you can use as free-standing toolbar icons.

As with all system-provided images, avoid using the template images to represent actions other than those they are designed for. Table 78-1 shows the standard template images available in macOS, along with the actions they represent and their names.

Table 78-1Template images that represent common tasks

Image

Meaning

Constant name

image: ../Art/NSQuickLookTemplate_2x.png

View in Quick Look

NSImageNameQuickLookTemplate

image: ../Art/NSBluetoothTemplate_2x.png

Connect via Bluetooth

NSImageNameBluetoothTemplate

image: ../Art/NSSlideshowTemplate_2x.png

View in a slide show

NSImageNameSlideshowTemplate

image: ../Art/NSActionTemplate_2x.png

Action pop-up menu

NSImageNameActionTemplate

image: ../Art/NSSmartBadgeTemplate_2x.png

Create smart item

NSImageNameSmartBadgeTemplate

image: ../Art/NSImageNameShareTemplate_2x.png

Share menu

NSImageNameShareTemplate

image: ../Art/NSIconViewTemplate_2x.png

View objects as icons

NSImageNameIconViewTemplate

image: ../Art/NSListViewTemplate_2x.png

View objects in a list

NSImageNameListViewTemplate

image: ../Art/NSColumnViewTemplate_2x.png

View objects in columns

NSImageNameColumnViewTemplate

image: ../Art/NSFlowViewTemplate_2x.png

View objects in a Cover Flow mode *

NSImageNameFlowViewTemplate

image: ../Art/NSPathTemplate_2x.png

View the path of the object

NSImageNamePathTemplate

image: ../Art/NSLockLockedTemplate_2x.png

Unlock the object (this image indicates the object is currently locked)

NSImageNameLockLockedTemplate

image: ../Art/NSLockUnlockedTemplate_2x.png

Lock the object (this image indicates the object is currently unlocked)

NSImageNameLockUnlockedTemplate

image: ../Art/NSGoRightTemplate_2x.png

Go to the right or go forward

NSImageNameGoRightTemplate

image: ../Art/NSGoLeftTemplate_2x.png

Go to the left or go back

NSImageNameGoLeftTemplate

image: ../Art/NSAddTemplate_2x.png

Add an item (to a list, for example)

NSImageNameAddTemplate

image: ../Art/NSRemoveTemplate_2x.png

Remove an item (from a list, for example)

NSImageNameRemoveTemplate

image: ../Art/NSEnterFullScreenTemplate_2x.png

Enter full-screen mode (deprecated)

NSImageNameEnterFullScreenTemplate

image: ../Art/NSExitFullScreenTemplate_2x.png

Exit full-screen mode (deprecated)

NSImageNameExitFullScreenTemplate

image: ../Art/NSStopProgressTemplate_2x.png

Stop progress on the current process

NSImageNameStopProgressTemplate

image: ../Art/NSRefreshTemplate_2x.png

Refresh the current view or restart the process

NSImageNameRefreshTemplate

*macOS does not provide programming interfaces that support adding a custom cover flow experience to your app.

System-Provided Images for Use as Standalone Buttons

macOS provides a handful of free-standing images that can be used as borderless buttons. These images don't require further processing by an NSButtonCell object.

Two of the free-standing images are standalone versions of similar template images. To see why you might need both versions of such an image, consider how Safari offers stop-progress functionality to users. In the downloads popover, Safari uses the free-standing NSImageNameStopProgressFreestandingTemplate image inline with a progress indicator to allow users to stop an in-progress download.

image: ../Art/freestanding_icon_in_use_2x.png

Because the Safari downloads popover can display several separate download processes at the same time, it’s important to display a stop-progress control for each individual process.

As with all system-provided images, each free-standing image must be used according to its documented meaning and recommended usage. Table 78-2 lists each image, along with its meaning and name.

Table 78-2Free-standing images that represent common actions

Image

Meaning

Constant name

image: ../Art/NSInvalidDataFreeTemplate_2x.png

The data on the left is invalid (for example, the user entered a zip code in a phone number field)

NSImageNameInvalidDataFreestandingTemplate

image: ../Art/NSRevealFreestandTemplate_2x.png

Reveal contents or details about the object

NSImageNameRevealFreestandingTemplate

image: ../Art/NSFollowLinkFreeTemplate_2x.png

Open the link in a new window or page

NSImageNameFollowLinkFreestandingTemplate

image: ../Art/NSStopProgressFreeTemplate_2x.png

Stop progress on the current process

NSImageNameStopProgressFreestandingTemplate

image: ../Art/NSRefreshFreeTemplate_2x.png

Refresh the current view or restart the process

NSImageNameRefreshFreestandingTemplate

System-Provided Images for Use as Toolbar Items

macOS provides several images you can use as standalone icons in toolbars. These images represent three types of items:

  • System entities or elements

  • Preferences categories

  • Common toolbar items

Use the images shown in Table 78-3 to represent system entities, such as the network and the user’s computer. For the most part, these entities don't have related actions. However, if you needed to represent an action, such as “create a new smart folder,” you could add a plus sign badge to the smart folder icon.

Table 78-3Images that represent system entities

Image

System element

Constant name

image: ../Art/NSBonjour_2x.png

Bonjour

NSImageNameBonjour

image: ../Art/NSNetwork_2x.png

Network or Internet

NSImageNameNetwork

image: ../Art/NSComputer_2x.png

The Macintosh computer currently running

NSImageNameComputer

image: ../Art/NSFolderBurnable_2x.png

A burnable folder

NSImageNameFolderBurnable

image: ../Art/NSFolderSmart_2x.png

A smart folder

NSImageNameFolderSmart

The images in Table 78-4 are intended for use as standalone icons in preferences window toolbars. Use these images to give users access to familiar preferences categories, such as user-account settings and advanced settings.

Table 78-4Images that represent common preferences categories

Image

Preferences category

Constant name

image: ../Art/NSAdvanced_2x.png

Advanced

NSImageNameAdvanced

image: ../Art/NSPreferencesGeneral_2x.png

General

NSImageNamePreferencesGeneral

image: ../Art/NSUserAccounts_2x.png

User accounts

NSImageNameUserAccounts

The images in Table 78-5 are suitable for toolbar items in windows other than preferences windows. You can use these images as standalone icons in a window or panel toolbar to give users access to the system-provided Colors and Fonts windows or to an Info or inspector window that you supply.

Table 78-5Images that represent standard toolbar items

Image

Toolbar item

Constant name

image: ../Art/NSInfo_2x.png

Show/hide information

NSImageNameInfo

image: ../Art/NSFontPanel_2x.png

Show/hide Fonts window

NSImageNameFontPanel

image: ../Art/NSColorPanel_2x.png

Show/hide Colors window

NSImageNameColorPanel

System-Provided Images that Indicate Privileges

macOS provides images that represent the standard “user,” “group,” and "all” categories of permissions or privileges, including access control lists (or ACLs). Each of these images is shown in Table 78-6, along with its meaning and name. It’s recommended that you use these images to clarify which users have permissions to read, write, or execute an item. These images allow you to avoid displaying Unix-style permissions indicators, such as rwxr-xrw-, which are suitable only for very sophisticated users.

Note that the “user group” permissions image shown in Table 78-6 looks similar to the image for the “user accounts” preferences category, shown in Table 78-4. As with all system-provided images, however, similar appearance does not imply similar meaning or usage. Always use system-provided images according to their semantic meaning.

Table 78-6Images that represent categories of user permissions

Image

Permissions category

Constant name

image: ../Art/NSUser_2x.png

User

NSImageNameUser

image: ../Art/NSUserGroup_2x.png

A user group

NSImageNameUserGroup

image: ../Art/NSEveryone_2x.png

All users

NSImageNameEveryone

A System-Provided Drag Image

macOS provides an image you can display when a user drags multiple documents or items. However, it’s best if you can provide more meaningful drag images (to learn more about this, see Drag and Drop).

image: ../Art/NSMultipleDocuments_2x.png

As with all system-provided images, use the multiple-documents image in accordance with its intended meaning. (The constant name of the drag image is NSImageNameMultipleDocuments.)