Alternate App Icons using Asset Catalogs in Xcode 13

If you had ever tried to add Alternate App Icons prior to WWDC 2021, you would have likely been frustrated after finding out alternate app icons must be added to the target file by file, without any easy way to see if you covered all the different sizes, and you had to manually define the structure for each icon in the Info.plist file.

An image of the property list file highlighting the keys needed to configure alternate app icons prior to Xcode 13.
The root key name even suggests this method of specifying app icons has been deprecated.

Well, no more! As of Xcode 13, Asset Catalogs now support Alternate App Icons and there’s a corresponding build setting to enable the feature:

At runtime, your app can now use iOS app icon assets from its asset catalog as alternate app icons. A new build setting, “Include all app icon assets,” controls whether Xcode includes all app icon sets in the built product. When the setting is disabled [sic], Xcode includes the primary app icon, along with the icons specified in the new setting, “Alternate app icon sets.” The asset catalog compiler inserts the appropriate content into the Info.plist of the built product. (33600923)

To show you exactly how this works, here’s a sample app made with SwiftUI:

The code for this app is the same as it would have been with versions prior to Xcode 13, except RelationshipIcon now refers to a new App Icon I’ve added to my default Asset Catalog:

And finally, to put it all together, we need to change two settings in the target’s Build Settings.

An image of the project’s Build Settings tab with the options filtered to “asset catalog” and “Customized” to show the changes to the “Alternate App Icon Sets” and “Include All App Icon Asset” flags.
An image of the project’s Build Settings tab with the options filtered to “asset catalog” and “Customized” to show the changes to the “Alternate App Icon Sets” and “Include All App Icon Asset” flags.
  1. In your project’s xcodeproj configuration, select the Build Settings tab.
  2. Under the Asset Catalog Compiler — Options group, change “Include All App Icon Assets” to Yes.
  3. Under the same group, add the names of your assets (the ones you used in the Asset Catalog) to “Alternate App Icon Sets”. Here I’ve only added RelationshipIcon but the option supports adding multiple icons.

And, voila!

A animated image demonstrating a screen with a single button that, when tapped, swaps the app icon between the default and an alternative icon.
A animated image demonstrating a screen with a single button that, when tapped, swaps the app icon between the default and an alternative icon.

The best part is that the new feature is in the build process itself, so you can start using this now with any apps targeting iOS 10.3 or later. As soon as Apple starts accepting apps built with Xcode 13, that is.