Supporting Dark Mode: In-App Web Content

If you’re using a web view the way a browser does, to show arbitrary content from the web, then you probably don’t need to do anything special to accommodate Dark Mode. If Dark Mode takes off then maybe we’ll see some kind of CSS standard around presenting web sites for dark presentations, but for the time being users expect web pages to look … like web pages.

On the other hand if you’re using web views to support an otherwise native Mac user interface, you’ll want to do something to adapt the default styling of your web content to look appropriate in Dark Mode. For example, I use a web view in my standard about box window. Here’s how it looked in MarsEdit before I adapted any web content to Dark Mode:

Screenshot of MarsEdit's about box with undarkened HTML content.

The two-tone look is kind of cool, but too much of an assault on the eyes for anybody who has really settled into Dark Mode. This content is not like a web page. It’s implemented in HTML to make features such as styling, layout, and links easier to manage, but as far as users are concerned it’s an innate part of this native About Box window.

I’ve seen a few approaches to adapting web content to Dark Mode, but most of them relied too heavily on modifying the actual HTML content that was being shown. In my apps, I use web views in several places and, rather than have to jump through hoops in each place to finesse the content for Dark Mode, I thought it would be better if I could come up with a common infrastructure that all web content presenters could use without typically being concerned about appearance.

Because my app is using both legacy WebView and modern WKWebView, I had to duplicate my efforts to some extent, but for the purposes of this article I’m going to focus on the approach I took for WKWebView.

My solution is rooted in arranging for a web view to call a pertinent JavaScript function when the effective appearance changes. Because WKWebView instances are notified via the viewDidChangeEffectiveAppearance method, I decided to subclass WKWebView to fulfill this contract on behalf of clients:

class RSAppearanceSensitiveWKWebView: WKWebView {

   var didInitialize = false

   // Override designated initializers to record when we're
   // done initializing, and avoid evaluating JS until we're done.

   override init(frame: CGRect, configuration: WKWebViewConfiguration) {
      super.init(frame: frame, configuration: configuration)
      didInitialize = true
   }

   required init?(coder: NSCoder) {
      super.init(coder: coder)
      didInitialize = true
   }

   public func updateContentForEffectiveAppearance() {
      // Don't try updating anything until we're done loading
      if didInitialize && self.isLoading == false {
         let funcName: String
         if self.effectiveAppearance.isDarkMode {
            funcName = "switchToDarkMode"
         }
         else {
            funcName = "switchToLightMode"
         }

         // Call the named function only if it is implemented
         let switchScript = "if (typeof(\(funcName)) == 'function') { \(funcName)(); }"
         self.evaluateJavaScript(switchScript)
      }
   }

   override func viewDidChangeEffectiveAppearance() {
      self.updateContentForEffectiveAppearance()
      if #available(macOS 10.14, *) {
         super.viewDidChangeEffectiveAppearance()
      }
   }
}

Instances of this subclass enjoy the benefit of two JavaScript functions, switchToDarkMode() and switchToLightMode(), being called whenever the view’s effective appearance changes. In case a client doesn’t wish the content to be adapted to Dark Mode, they can simply omit the functions from the content they load into the view.

Because I don’t want to duplicate efforts to handle appearance switching throughout my apps, I implemented basic support for mode switching in my centralized “web content display” class, RSWebContentViewController. This controller takes advantage of WKWebView’s support for injecting JavaScript, to add support for switching modes to whatever content the client provided:

let appearanceModeScriptSource = """
   var darkModeStylesNodeID = "darkModeStyles";

   function addStyleString(str, nodeID) {
      var node = document.createElement('style');
      node.id = nodeID;
      node.innerHTML = str;

      // Insert to HEAD before all others, so it will serve as a default, all other
      // specificity rules being equal. This allows clients to provide their own
      // high level body {} rules for example, and supersede ours.
      document.head.insertBefore(node, document.head.firstElementChild);
   }

   // For dark mode we impose CSS rules to fine-tune our styles for dark
   function switchToDarkMode() {
      var darkModeStyleElement = document.getElementById(darkModeStylesNodeID);
      if (darkModeStyleElement == null) {
         var darkModeStyles = "body { color: #d2d2d2; background-color: #2d2d2d; } body a:link { color: #4490e2; }";
         addStyleString(darkModeStyles, darkModeStylesNodeID);
      }
   }

   // For light mode we simply remove the dark mode styles to revert to default colors
   function switchToLightMode() {
      var darkModeStyleElement = document.getElementById(darkModeStylesNodeID);
      if (darkModeStyleElement != null) {
         darkModeStyleElement.parentElement.removeChild(darkModeStyleElement);
      }
   }
"""

let appearanceModeScript = WKUserScript(source: appearanceModeScriptSource, injectionTime: .atDocumentEnd, forMainFrameOnly: true)
self.webView.configuration.userContentController.addUserScript(appearanceModeScript)

Copy this into Xcode for easier reading, but the gist of it is to implement switchToDarkMode() by injecting CSS rules that alter the baseline defaults for the web content, and implement switchToLightMode() by removing those CSS rules. This is what my about box looks like after adopting the changes above:

Screenshot of MarsEdit's about box window after the HTML content has been adapted to Dark Mode

This approach requires clients of RSWebContentViewController to trust that the default appearance switching will be sufficient for whatever content it wants to display. So far this simple approach has been sufficient for my needs, but I’m also in a good position to expand upon the solution should the need arise.