Adding icon composer icons to xcode

How do you use icon composer to add app icons to an xcode project?

Last Updated: Jun 26, 2025

Icon composer

Xcode 26 Adds A New Icon Composer tool to Build ICons for the New Liquid Glass Design System. I recommend the apple article: Creating your app icon using icon composer and the wwdc videos linked below to learn how to best use icon composer.

The basic idea is that you use your preferred design tool (Photoshop, sketch, pixelmator, etc.) to design your icon’s foreground layers. You then expert these as full opaque svg layers to important into icon composer.

Using icon composer, you add the background, adjust size and positions of the layers, set opacity, color/gradients, shadows, and glass effects. Xcode uses the single .icon file to generate all the icon variants it needs for all supported platforms.

Adding icons to an xcode project

The step that left me confused when watching the wwdc video was how to add the icons to an xcode project.

You no longer need to add default, dark, and tinted variants of the app icon to the asset catalog in the app bundleWhat you need to do is drag the icon composer .icon file into the project Navigator Sidebar of the Xcode Project:

Once you add the .icon file to the project you no longer need the external file. You can open and edit the icon file in icon composer directly from xcode:

I would prefer that we could avoid this two step process. Maybe apple will add an icon composer template to xcode so we can create a new icon file directly in the project (FB18297643).

One final step, in your app target settings, Make sure the app icon set name matches the name of the icon composer icon file name (without the .icon extension),

What about alternate app icons?

One thing that is missing is support for alternate app icons. I expected to be able to add alternate app icons to the project using icon composer. For example, if I create a purple variant of the icon named appicon-purple.icon and add it to the project:

That should be enough for xcode to generate the icons (Making sure to have “Include all app icon assets” enabled in the building settings – see Above). Unfortunately, setting the alternate icon name fails:

UIApplication.shared.setAlternateIconName("AppIcon-purple")

Investigating some reports from people that claimd to have it working i decide to compare what xcode generates when I add the app ICONS to the Asset Catalog. This is what i see in the info.plist:

Adding those keys to the info.plist of the target fixes the problem. Note that the ~ iPad variant seems to be Necessary for it to work on the ipad. Hopefully apple fixes this in a future xcode release (FB18233873).

Backwards Compatibility

One other problem I’ve seen is icons not rendering correctly on older iOS releases. For example, on iOS 16.4 the background is not rendered. This looks like a knowledge issue, the workaround being to keep the asset catalog icons:

Icon composer icons back deploy to older versions of iOS, Macos, and Watchos with inconsistent rendering. (152258860) Workaround: Keep the Previous Asset Catalog App Icon in your project until this issue is resolved.

Learn More