Paint It Black: Dark Mode in macOS Mojave

Mohammad Asgharneya

3 min read

Jun 6, 2018


Paint It Black: Dark Mode in macOS Mojave

Starting with macOS Mojave, users can choose to run a system-wide light or dark mode of the Aqua interface. While opting an application into light and/or dark appearance modes is ultimately the choice of the developer, users may come to expect that apps support both. Apple believes some content creation applications may make sense primarily as dark mode only applications.


Standard views and controls are ready for Dark Mode out-of-the-box. And if you’re already using asset catalogs and semantic colors, you’ll be able to make your app ready too with minimal code changes.

Our Astronomical app was designed using just the Aqua interface but we would like to support Dark Mode as well. We first built the app using the macOS 10.14 SDK, but it seems like we have some work to do.

Sample Astronomical app in light mode and Broken Astronomical app in dark mode

Our header text was previously hardcoded to but we can easily achieve the same result using the dynamic .headerTextColor which will now do the right thing when we switch appearances.

Sample Astronomical app in light mode with header text that changes colors properly

Next, we would like to change our sun asset to a moon to represent dark mode. This can be achieved using the Asset Catalog. The Asset Catalog provides a convenient way to return a different resource using the same name that varies based on device attributes. In our case, the device attribute that is changing is the Appearance.

asset catalog screenshot

Note: If you are still targeting 10.13 or earlier, trying to receive a named image asset will only return the “Any Appearance” versions.

Nearly complete dark mode conversion, but emoji text is still not updated

Detecting Appearance Changes Programmatically

There are some cases where you may want to respond to appearance changes programmatically. You may have already noticed that Xcode 10 is nice enough to remember your Source Editor theme preference for each appearance. We would like to use this trigger to update our emoji representation of the Astronomical object we are presenting on screen.

How can we do something like this in our code? We can detect appearance changes by observing effectiveAppearance from the newly formalized NSAppearanceCustomization protocol. This protocol has informally existed for a while, but is now adopted by NSPopover, NSView, NSWindow, and NSApplication (new as of 10.14).

You can use KVO to observe changes to effectiveAppearance.

override func viewDidLoad() {
    appearanceChangeObservation = view.observe(.effectiveAppearance) { [weak self] _, _  in

Once you detect an appearance change, you will want to figure out which appearance the application is currently in. Switching on will work, but switching on bestMatch(from:) may be a more future-proof approach. This method will attempt to provide you a good match based on the appearances you provide as the parameter.

private func updateAppearanceRelatedChanges() {
    switch view.effectiveAppearance.bestMatch(from: [.aqua, .darkAqua]) {
    case .aqua?: emojiField.stringValue = "☀️☀️☀️"
    case .darkAqua?: emojiField.stringValue = "🌙🌙🌙"
    default:  emojiField.stringValue = "💫💫💫"

Successful dark mode conversion of the Astronomical app

Update Custom Views Using Established Methods

While our Astronomical app didn’t need to override the methods below, it is worth mentioning that these methods are the ideal place to update views when appearances change. Depending on your implementation, some of these NSView methods will be called when an appearance changes:

  • updateLayer()
  • draw(_:)
  • layout()
  • updateConstraints()

You can trigger these methods manually by setting needsLayout, needsDisplay, and needsUpdateConstraints.

We can’t wait to see how great your apps look in dark mode!

Steve Sparks

Reviewer Big Nerd Ranch

Steve Sparks has been a Nerd since 2011 and an electronics geek since age five. His primary focus is on iOS, watchOS, and tvOS development. He plays guitar and makes strange and terrifying contraptions. He lives in Atlanta with his family.

Speak with a nerd

Schedule a call today! Our team of nerds are ready to help

Let's Talk

Related Posts

We are ready to discuss your needs.

Stay in Touch WITH Big Nerd Ranch News