Icon Composer Notes
I would not have figured out how to use this tool without help, so I wanted to pass along the correct way to use it.
[…]
On macOS, one sets an alternate icon by drawing it in code using the NSDockTile API. I believe Mac apps have no access to the system-wide Icon & widget style setting or the current tint color.
You can create an icon using
NSImage(named: String)and display it in the app with anNSImageView. If the icon has any variation between the light mode version, dark mode version, or mono version, the image drawn shows the mono version.When I add multiple
.iconfiles to a Mac app, Xcode seems to only include the app’s default icon. It seems to ignore the others. The icon is included as a.icnsfile that appears to be generated from the.iconfile. It is probably possible to generate those.icnsfiles some other way and include those as resources.
See also: Brad Ellis (via Mastodon).
Previously:
Update (2025-06-24): Keith Harrison:
You no longer need to add default, dark, and tinted variants of the app icon to the asset catalog in the app bundle. What you need to do is drag the Icon Composer .icon file into the project navigator sidebar of the Xcode project[…]
[…]
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)[…]
[…]
One thing that is missing is support for alternate app icons.
Update (2025-06-26): Sam Rowlands:
What am I doing wrong? Tahoe icons.
- Created Icon in Icon Composer.
- Added .icon file to Xcode project (not assets section).
- Renamed it to AppIcon.icon.
But it won’t show either when running or when archiving.
Update (2025-07-16): Megabits:
Different software may structure SVG differently, similar to how Dreamweaver used to include unnecessary code when creating web pages. This can affect how Icon Composer interprets the files. I recommend checking all exported SVG images with a text editor.
[…]
After handling light and dark modes, you’ll need to address monochrome mode. You may notice that icons in monochrome mode appear grayish. Initially, I thought this was normal for monochrome mode, but upon testing on an actual device, I found it to be much darker than other apps.
This issue occurs because Icon Composer calculates monochrome brightness based on the brightness of colors in normal mode.
[…]
Icon Composer has many limitations. The first is the layer limit.
Update (2025-07-28): John Brayton:
Something to be aware of with Icon Composer: Tinted variants of icons generated from Icon Composer look as expected on iOS 26, but look terrible on iOS 18.
For every Liquid Glass app icon I make, I wish I had way more control over the specular highlights. Thickness, inset from edge, brightness. I want to play with the variables that are possible, but they don’t extend to us. I want to designate a completely transparent layer as a specular highlight mask.
Instead, I’m just baking in my own lighting, knowing full well that it won’t be native. But it looks better. The tools they provide are neat in theory, but very limited in practice.
Update (2025-08-01): Louie Mantia:
I’m really worried about how creating an icon inside Icon Composer—with the effects it supports—renders differently in Icon Composer from when it’s bundled in the app.
Not only that, but when using SVGs that have colors, gradients, and effects, Icon Composer will interpret them how it wants to. An inner glow from edge was interpreted as an inner glow from center. You know, the opposite.
With a static image, you never have these problems. But when rendering dynamically, you absolutely will.
Sarah Reichelt (via Der Teilweise):
If you want to support older systems and have an AppIcon set in Assets.xcassets, set the name of your Icon Composer file to AppIcon and your app will use the new one and fall back to the old one if required.
Update (2025-08-08): James Thomson:
If you were thinking “should I add 50 custom icons to my iOS 26 app?”, let me tell you about how it now takes me 5-10 minutes to rebuild my asset catalog on an M1 Ultra Mac Studio as it renders all of them.
Previously:
Update (2025-09-08): Jordan Morgan:
For the life of me, this thing is simplistic yet confusing at times.
[…]
What really tripped me up was that I started by choosing a dark mode icon, and I thought, “Okay, it clearly says “Dark” here, so I’ll hide the light layers now.” But, going the other way was confusing to me — because you don’t select a “Light” toggle at that point. Instead, it’ll say “Default” with no option to choose or add anything else. What this is trying to say is “The changes here apply to light mode.”
Update (2025-09-11): Craig Hockenberry:
Pro Tip: You can use Icon Composer to create an .icon file that mimics the behavior of previous iOS releases AND works well on macOS Tahoe.
You do it by completely avoiding effects and just use the opacity setting for the Default/Dark/Mono modes.
Create three groups (Tint, Light, and Dark below) and add flat artwork to each group. Then, under Color, set the Opacity for the images in each mode. For example, the Light group image is 0% in Dark/Mono mode and 100% in Default mode.
Much easier.
1 Comment RSS · Twitter · Mastodon
I've gotten composer icons to load with NSImage imageNamed: from Xcode 26 final builds, but I haven't figured out how to make it load any variation other than the light style.
