Saturday, March 20, 2021



Theme Compliant Preferences for Big Sur and below

How to adapt your Preferences Window toolbar so it looks and works like an Apple app on macOS Big Sur and consistent with previous OS Versions.

Saturday, March 20, 2021 - Sam Rowlands

A common question I get asked, is how to make a Preferences Window look and work consistently with macOS Big Sur, while still looking and working consistently with older versions of the macOS.

Preferences Dialog in macOS Big Sur

Preferences Dialog in macOS Big Sur

Preferences Dialog in macOS Mojave

Preferences Dialog in macOS Mojave

Start with the toolbar

Preferences Toolbar in the Xojo IDE

Layout the toolbar in the Xojo IDE, adding only the buttons to use for switching the pane. Make sure all the buttons are "ToggleButton" in the IDE. You can specify icons here, but they'll be overwritten when running on Big Sur, so I personally don't bother.

Add some code

The following code uses the Ohanaware App Kit, but you should be able to translate it to whatever application kit that you're using. Place it in the "Open" event of the window.

The property "app.fullColorIconsUse" allows my users to choose between Big Sur consistency or easily recognizable icons.

The code works by using NSArrayObjectAtIndex( items, 0 ) to get the toolbaritem, NSControlSetImage then sets the image on the item. NSImageFromName will load images from either the system or that are contained in the Resources folder of the application, while NSImageWithSymbolName will use a SF Symbol as the image. SF Symbols only work on macBS or newer.

#if targetMacOS then Dim tHandle as integer = NSWindowToolbar( self.handle ) Dim items as integer = NSToolbarItems( tHandle ) if operatingSystemisAtLeastBigSur then // If we're on macBS, tell the window to use the Preference style toolbar. NSWindowSetToolbarStyle( me.handle ) = NSWindowToolbarStyleValue.preference end if if app.fullColorIconsUse or operatingSystemisAtLeastBigSur = false then // --- If the user has choosen full color icons or is running on an older version of the macOS NSControlSetImage( NSArrayObjectAtIndex( items, 0 ) ) = NSImageFromName( "NSImageNamePreferencesGeneral" ) NSControlSetImage( NSArrayObjectAtIndex( items, 1 ) ) = NSImageFromName( "NSImageNameUserAccounts" ) NSControlSetImage( NSArrayObjectAtIndex( items, 2 ) ) = NSImageFromName( "interfaceIcon" ) else // --- macBS, so use SF Symbols. NSControlSetImage( NSArrayObjectAtIndex( items, 0 ) ) = NSImageWithSymbolName( NSImageClass, "gearshape", "general" ) NSControlSetImage( NSArrayObjectAtIndex( items, 1 ) ) = NSImageWithSymbolName( NSImageClass, "", "accounts" ) NSControlSetImage( NSArrayObjectAtIndex( items, 2 ) ) = NSImageWithSymbolName( NSImageClass, "macwindow.on.rectangle", "Window" ) end if #endIf


You need to mark your Xojo made application as BS compatible, to do that you currently need to use App Wrapper.

If you don't have an active license plan for App Wrapper, you can always take advanatge of the 14-Day trial by downloading it from

  1. Open the App Wrapper document for your application.
  2. Select "Advanced Options" from the "Edit" menu.
  3. Enable "Executable minimum macOS & SDK", then set the "SDK" to "11.0.0".
  4. Save the settings and save the document.
  5. If you don't already have the scripting set-up, now's a good time to do that. See the App Wrapper help on how to integrate with Xojo.
  6. Run the project and enjoy the BS themeing.