Article

Choosing a Specific Appearance for Your App

Override the system appearance when needed to implement the interface style that makes sense for your app.

Overview

In macOS 10.14 and later, users can choose whether they want their system to adopt a light or dark appearance. Apps linked against the macOS 10.14 SDK are assumed to support both appearance types unless they explicitly opt out.

Adopting both light and dark appearances is strongly encouraged, but there are good reasons to opt out some or all of your interface. For example, views containing printable content should reflect what the user will see on the printed page, which typically means using a white background at all times. Similarly, user-created content should not change appearances with the rest of your app’s chrome.

You may choose which appearance—light or dark—to adopt for your entire app or for specific views, windows, or popovers. You can also disable support for dark appearances entirely using an Info.plist key.

Assign a Specific Appearance to a View or Window

When you want a view or window to adopt a specific appearance, assign a custom NSAppearance object to it. Normally, appearance information is inherited. Your app object inherits the system appearance and propagates that appearance to all windows and panels that you display. If you assign a specific appearance to an object in your view hierarchy, all subviews of that view inherit the new appearance.

To assign a specific appearance to a view or window in your storyboard file, change the appearance attribute in the inspector, as shown in Figure 1.

Figure 1

Selecting the appearance for a view

Choosing a specific appearance from the Appearance pop-up menu in the attributes inspector causes the view to always adopt that appearance.

To make the same change programmatically, assign the appropriate NSAppearance object to the view’s appearance property. Listing 1 shows a method that assigns the Aqua appearance to a view. Each of the view's initialization methods calls this method.

class MyContentView : NSView {

  func adoptAquaAppearance()
      self.appearance = NSAppearance(named: .aqua)
   }

}

Assign a Specific Appearance to Your App

To adopt a specific appearance for your entire app, assign a value to the appearance property of your NSApplication object. Choose an app-wide appearance only when required by your design. For example, you might always want your photo editing app to have a dark appearance so users can focus on their photos and not your app’s chrome. Listing 2 shows how to assign the dark appearance to your app.

NSApp.appearance = NSAppearance(named: .darkAqua)

Opt Out of Dark Mode

Apps linked against macOS 10.14 or later should support both light and dark appearances. If you build your app against an earlier SDK, you can still enable Dark Mode support by including the NSRequiresAquaSystemAppearance key (with a value of false) in your app's Info.plist file. Do so only if your app's appearance looks correct when running in macOS 10.14 and later with Dark Mode enabled.

If you need extra time to work on your app's Dark Mode support, you can temporarily opt out by including the NSRequiresAquaSystemAppearance key (with a value of true) in your app’s Info.plist file. Setting this key to true causes the system to ignore the user's preference and always apply a light appearance to your app.

See Also

Appearance Support

Providing Images for Different Appearances

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