Providing Images for Different Appearances

Supply image resources that work for light and dark appearances and for high contrast environments.


Wherever you use images as part of your interface, make sure those images look good in both light and dark interfaces. Images are often used to implement buttons, and you can also display images in backgrounds or in custom views and controls. The best way to specify your app's images is using asset catalogs, which let you provide different images for light and dark appearances. However, there are other ways to provide images that support both appearances.

Customize Image Assets for Different Appearances

Asset catalogs make it easy to manage images for both light and dark appearances. A single, named asset stores all of the versions of the image you need. When you create the resulting NSImage object, you specify only the name of the asset. AppKit automatically loads the version of the image that matches the appearance settings on the user's system. And if the appearance settings change, AppKit automatically refreshes your image object using the new settings.

Use the inspector to enable the dark appearance for an image asset, and then provide custom resources for light and dark appearances.

An image asset can adapt to changes in any of the following conditions:

  • Screen resolution. Supply images for regular and Retina displays. AppKit picks the image that best matches the resolution of the current screen.

  • Light and dark appearances. Customize the images you use for light and dark appearances. Put light images in either the Any Appearance slots or the Light Appearance slots. Images in the Light Appearance slots are available only in macOS 10.14 and later. Images in the Any Appearance slots are available on all versions of macOS.

  • High contrast. Specify images that stand out more from the surrounding content. Enable the High Contrast option in the inspector to add slots for your high contrast images. High contrast images are available only in macOS 10.14 and later.

AppKit chooses the specific image based on the current system settings. The appearance option in the General pane of the System Preferences app determines whether AppKit selects a light or dark image. The increase contrast option in the Display settings of the Accessibility system preference determines whether AppKit chooses a high contrast or normal contrast image.

Use Template Images

An alternative to providing multiple images for different appearance configurations is to provide a single template image that adapts to all environments. Typically, you use template images to represent iconic shapes. For example, you might use template images to represent the play and pause buttons of a media app. Only the opacity of pixels in a template image matters.

When displayed in your interface, the underlying view provides the tint color for your template image. For example, a button uses the standard tint colors for control content, which updates automatically based on the current appearance.

Views apply tints to a template image to make it stand out against the background. The tint colors change based on whether the view is displayed with a light or dark appearance.

Use your favorite image editor to create a template image files. When creating your image, use a transparent background and add black pixels wherever you want the image to appear. The pixels can be fully or partially opaque, depending on whether you want portions of your template image to blend with the background colors. When adding the image to your asset catalog, set the Render As option for the Image Set asset to Template Image in the inspector.

Create Images with a Drawing Handler

When designing your app’s interface, you typically create images at design time and include them in the app bundle that you ship. However, you can also create images dynamically, which you might do if you don’t yet know what the image content will be, or if that content is changeable.

To create an image that draws its contents, use imageWithSize:flipped:drawingHandler:. AppKit calls your drawing handler block whenever the system appearance changes, giving you a chance to recreate the image using the new appearance.

See Also



A high-level interface for manipulating image data.


A set of optional methods that you can use to respond to drawing failures and manage incremental loads.


A semiabstract superclass that provides subclasses that you use to draw an image from a particular type of source data.