The apple-touch-icon: size, tag and common mistakes
When someone adds your site to an iPhone home screen, iOS uses the apple-touch-icon. The 180px size, the one tag you need, and why transparency turns black.
When someone taps Share and Add to Home Screen on an iPhone, iOS needs an icon for your site. It does not use the favicon or the web manifest's icons first. It looks for an apple-touch-icon, and without one it makes a thumbnail of the page, which rarely looks good.
The file and the tag
<link rel="apple-touch-icon" href="/apple-touch-icon.png">One 180 by 180 PNG covers current devices. Put it at /apple-touch-icon.png as well, because iOS and some other tools request that path directly even without a tag.
Three common mistakes
- Transparency. Transparent areas render as a solid colour on the home screen, often black. Use an opaque background.
- Rounded corners in the file. iOS applies its own corner mask. Deliver a square.
- The logo edge to edge. Leave padding around the mark so the corner mask does not clip it.
These are the same rules as a native iOS app icon, for the same reason. See iOS icons and transparency.
Does the web manifest replace it?
Not on iOS. Safari reads the manifest for some things, but the home screen icon has long come from the apple-touch-icon, and it is the reliable choice. Android and desktop Chrome read the manifest icons instead. Providing both costs one extra file.
Test it
Open the site on an iPhone, tap Share, then Add to Home Screen, and look at the preview before confirming. If you see a screenshot of your page instead of your icon, the tag or file path is wrong. If you see black corners, the file has transparency.
Where it fits in the set
The apple-touch-icon is one of four or five files every site needs, alongside favicon.ico, an SVG icon and the manifest icons. Favicon sizes has the complete set and the tags.
App Icon Foundry includes the apple-touch-icon in its web export, opaque and square, with the head tags to paste in, from the same design as your app icons.
Questions
What size should the apple-touch-icon be?
180 by 180 pixels covers current iPhones. iOS scales it for other devices, so one file is enough.
Why is my home screen icon black around the edges?
The PNG has transparency. iOS does not show transparent areas of a touch icon as transparent; they render as a solid colour. Give the icon an opaque background.
Do I still need apple-touch-icon-precomposed?
No. It was for very old iOS versions that added a gloss effect. Modern iOS ignores the distinction; use apple-touch-icon.