iosxcodeappiconios26icon-composer

How do I add Icon Composer glass app icons to my existing pre-iOS 26 app (and support alternate glass icons)?

I have an existing iOS app that supports from iOS 15 to iOS 18 at the moment. My app has its main app icon plus several alternate app icons. All of my existing app icons are in an image asset. The app icon assets are named AppIcon, AppIcon2, AppIcon3, etc. That all works just fine. I can call UIApplication setAlternateIconName with the different names and the different icons are applied.

Using Xcode 26 I'm trying to add new "glass" app icons made with Icon Composer. My goal is to have the old style icons be used when run on devices with iOS 15 - 18 and to have the new glass icons be used when run on devices with iOS 26+. I used the new Icon Composer tool to create a new glass app icon. I saved the new icon file as AppIconGlass.icon and then added that file to my project.

On the target's General tab I went to the "App Icons and Launch Screen" section and changed "App Icon" to "AppIconGlass". I also enabled the "Include all app icon assets" option.

When I build and run my app on a simulated iOS 26 device, I am getting the new glass icon. Great. But when I run my app from Xcode 26 on an iOS 15-18 device or simulator, I am getting weird versions of the new glass icon instead of the expected old style icon it has always used.

So how you support both styles of icons? And how do you support alternate glass icons under iOS 26? Adding additional glass icons, such as AppIconGlass2.icon to the project doesn't let you use the icon "AppIconGlass2" in the call to UIApplication setAlternateIconName.

Solution

  • It turns out that supporting both old and new app icons, including alternate app icons, in an app that runs on iOS 18 or earlier as well as iOS 26 it very easy.

    The trick is in the app icon naming. If your existing app icon assets are named AppIcon, AppIcon2, AppIcon3, etc., then when you add the glass .icon files to your project, name them the same as the corresponding app icon asset. In other words, the main glass app icon will be named AppIcon.icon. The alternates will be named AppIcon2.icon, AppIcon3.icon, etc. Or if your existing app icon assets are named MainIcon, Icon-Red, Icon-Blue, etc., then the new glass icon files need to be named MainIcon.icon, Icon-Red.icon, and Icon-Blue.icon.

    Then on the target's General tab, you leave the App Icon setting just as it was. The value, in this example, will remain "AppIcon". Also be sure the "Include all app icon assets" option is enabled.

    That's it. Do not manually add any icon related entries to Info.plist. If you've added any in the past, remove them. This includes the raw keys CFBundleIcons and CFBundleIcons~ipad. When you build the app in Xcode (16 or 26), it will add the appropriate entries for the app icons.

    It boils down to this - when your app runs under iOS 18 or earlier, the OS looks in the Info.plist and it finds the automatically added entries for the primary and alternate icon names. It uses those names to find matching app icon image assets bundled in the app. When your app runs under iOS 26, the same values are found in Info.plist. But iOS 26 doesn't look for the older app icon image assets. It looks for the newly packaged glass icons files with matching names.

    Here's more details with pictures.

    I created a new iOS project with Xcode 26 and set the deployment target to iOS 18. I then added the main app icon (AppIcon) and 2 alternate app icons (AppIcon2, AppIcon3) in the default Assets file.

    iOS 18 app icon assets

    Then I ensured the App Icon settings were correct on the General tab.

    General Tab

    Using Icon Composer, I created three new glass app icons. I named them AppIcon.icon, AppIcon2.icon, and AppIcon3.icon. I then dragged the 3 .icon files to my project in Xcode.

    Glass Icons

    That's all that is needed. Run the app under iOS 18 and get the AppIcon from Assets. Run the app under iOS 26 and get the glass icon from AppIcon.icon. If you have code that calls UIApplication setAlternateIconName with "AppIcon2" then you get the appropriate alternate app icon for the version of iOS the app is running on.

    Note that there are no Icon related entries shown on the Info tab of the project:

    Info tab

    However, if you look at the generated Info.plist that is bundled with the built app, you do get the following entries:

    <key>CFBundleIcons</key>
<dict>
    <key>CFBundleAlternateIcons</key>
    <dict>
        <key>AppIcon3</key>
        <dict>
            <key>CFBundleIconName</key>
            <string>AppIcon3</string>
        </dict>
        <key>AppIcon2</key>
        <dict>
            <key>CFBundleIconName</key>
            <string>AppIcon2</string>
        </dict>
    </dict>
    <key>CFBundlePrimaryIcon</key>
    <dict>
        <key>CFBundleIconFiles</key>
        <array>
            <string>AppIcon60x60</string>
        </array>
        <key>CFBundleIconName</key>
        <string>AppIcon</string>
    </dict>
</dict>

    There's also a corresponding entry for CFBundleIcons~ipad.

    After you create the glass icon in Icon Composer, simply use the File | Save menu. That creates the .icon file that you add as-is to the project in Xcode. Do not make any attempt to add the glass icon to the Assets file. There's no need to use the File | Export menu in any way to add the glass icon to the project.

    A quick note about using Icon Composer. Apple has the article Creating your app icon using Icon Composer. Near the end of the article is the section Add your Icon Composer file to an Xcode project.

    There is the statement:

    Just drag the Icon Composer file from Finder to the project navigator, and Xcode provides feedback on where to drop it in a target folder.

    This is confusing. I'm guessing by "feedback" they mean the blue bar that appears whenever you drag a file around.

    And there is this note:

    The latest version of Xcode uses the Icon Composer file instead of an existing AppIcon asset catalog in your project.

    This is misleading. If you use Xcode 26 to build your app, then when the app is run on a device or simulator with iOS 26, then the Icon Composer file (glass app icon) is used. But if the app is run on a device or simulator with iOS 18 or earlier, it will use the existing AppIcon asset catalog as it always has.