Xcode: What’s up with App Icons?

4 min readAug 2, 2018

When you create an image set in Xcode, it’s so easy to automatically fill the wells for each scale factor. You just need to give each the three scale factor image files the correct syntax, something like:

image.png
image_2x.png
image_3x.png

Drag them in and Xcode automatically detects the correct well for each image, and tada!

So you’d think it would be just as easy to set up an app icon in the asset catalog. There is some automation there, but weirdly it’s a bit hit and miss.

Let’s look at what we can do about this.

Generating App Icon files

First, how to set up all of these versions of the app icon?

Easy! Apple provides a Photoshop (or Sketch or Adobe XD) template in the resources section of HIG for setting up an icon, that looks something like:

Once you’ve set up your icon, you can specify File > Generate > Image Assets:

And this will output all the files you’ll need to create an app icon:

Adding icons to Asset Catalog

However, as we saw, when you drag these icons into your app icon:

Only some wells fill, others stay blank, and some files are treated as unassigned:

Your first question might be:

My guess is this is a bug in Xcode. If anyone has more info on this feel free to add a comment here. But maybe a more pertinent question is…

What to do about this?

Fix it manually

So — of course one solution is to resolve this manually. We could drag files one by one into their correct wells. Boring! We want automation!

Fix the automation

So, if you right-click on the app icon in the asset catalog, and select ‘Show in Finder’:

Here you’ll find all of the icon files inside the project, along with a ‘Contents.json’ file:

Here’s where the magic lives! Contents.json is a file used by the asset catalog to describe its assets (or folders, metadata, etc.) If you open the Contents.json file for the AppIcon you’ll find that it describes all of the app icon files, blank wells and unassigned images, something like this:

All the files we need are in the App Icon folder in the Asset Catalog, we just need them to be assigned correctly in the Contents.json file. If we’ve used the Photoshop template, our files will have the same names every time, so we can simply replace the Contents.json with a standard Contents.json file that has been set up with the correct description of the files, and everything should automatically drop into the correct wells!

So, as a recap, here are the steps to follow after generating your icon files from Photoshop:

Select all of the files you’ve generated (except for Icon-App-60×60@1x.png, this file is no longer included in the app icon package) and drag them as per usual into the App Icon in the Assets Catalog in Xcode.
Right-click on the App Icon, and select Show in Finder. Here you’ll find the Contents.json file.
Replace this Contents.json file with a corrected Contents.json file. (You can find a gist for this file here.)
Tada!

There’s an app for that!

Alternatively, you can try out a third party solution. Be careful though, there are plenty (even paid Mac programs) that merely create the files for you (exactly what the Photoshop template does for you) without helping you to integrate these files into Xcode.

Icon Set Creator (link here) is free and not only generates the files for you, but also generates the Contents.json file. This means you can simply import this folder into the Asset Catalog and the files will slot into their wells.

Interested to learn more on using Swift for building apps in iOS?

Click on the link to check out my livevideo course, iOS Development with Swift in Motion.

Check out an intro video here.