Docs / Apple Touch Icon Implementation

Documentation

Complete technical guides for implementing, optimizing, and deploying Apple Touch Icons across web and mobile platforms.

Overview

Apple Touch Icons are specialized image assets used by iOS and macOS Safari to represent web pages when added to the Home Screen. This documentation covers all technical requirements, implementation patterns, and optimization strategies for delivering pixel-perfect touch icons.

📚 Note

While originally created for Apple devices, modern implementations support cross-platform fallbacks for Android, Windows, and desktop browsers via the Web App Manifest.

Icon Sizes & Formats

Apple devices require specific resolutions to ensure crisp rendering across different screen densities. Use the following table as your implementation reference:

Device / Target	Recommended Size	Filename	Precomposed
iPhone (Modern)	180 × 180 px	`apple-touch-icon.png`	Required
iPad / Retina	167 × 167 px	`apple-touch-icon-167.png`	Optional
iOS 7+ Fallback	152 × 152 px	`apple-touch-icon-152.png`	Deprecated
Legacy WebClip	120 × 120 px	`apple-touch-icon-120.png`	Optional
Favicon Fallback	32 × 32 / 16 × 16 px	`favicon.ico`	Not applicable

Key Requirements:

Use PNG format with transparency (alpha channel)
Do NOT apply rounded corners, shadows, or gloss effects in the image itself (Safari applies these automatically)
Place icons in the document root directory for maximum compatibility

HTML Meta Tags

Insert the following meta tags within the <head> section of your HTML document:

<!-- Primary Apple Touch Icon -->
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">

<!-- iPad Retina -->
<link rel="apple-touch-icon" sizes="167x167" href="/apple-touch-icon-167.png">

<!-- Web App Manifest (Cross-platform) -->
<link rel="manifest" href="/site.webmanifest">

Precomposed Attribute

For iOS versions prior to 7, you may need the precomposed attribute. Modern implementations typically omit it, but include it if targeting legacy systems:

<link rel="apple-touch-icon-precomposed" sizes="180x180" href="/apple-touch-icon-precomposed.png">

Platform Implementation Guides

iOS & macOS Safari

Safari automatically requests /apple-touch-icon.png from the document root. If not found, it falls back to the favicon. To enforce a specific icon, use the meta tag approach above.

Android / Chrome

Android uses the Web App Manifest. Include icon references in your site.webmanifest:

{
  "name": "My Application",
  "icons": [
    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" }
  ]
}

React / Next.js

In Next.js App Router, icons are automatically handled via the icon.tsx or favicon.ico file. For custom touch icons:

export const metadata = {
  appleWebApp: {
    capable: true,
    statusBarStyle: 'default',
    title: 'My App',
  },
  icons: {
    apple: [{ url: '/apple-touch-icon.png', sizes: '180x180', type: 'image/png' }],
  },
}

Best Practices

Design on a transparent background: Safari applies its own rounded rectangles and drop shadows. Designing these into the image will cause double-effect rendering.
Center your artwork: Leave a 5-8% safe margin to prevent clipping on older devices.
Optimize file size: Keep PNG files under 200KB. Use tools like ImageOptim or TinyPNG.
Test on physical devices: Simulator rendering differs from actual iOS Safari behavior.
Use SVG for scalability: Generate PNGs from vector sources to ensure crisp edges at all resolutions.

Troubleshooting

Icon not appearing on Home Screen

Ensure the file is named exactly apple-touch-icon.png and placed in the root directory. Clear Safari's cache and test on a device, not a simulator.

Icon appears rounded or shadowed twice

Remove all corner radiuses, shadows, and gloss from the source image. Safari applies these automatically since iOS 5.

Low resolution on Retina displays

Verify you're serving the 180×180px version. Check your meta tags' sizes attribute matches the actual file dimensions.

Changelog

v2.4.0 (2024-12-01) — Added Next.js 14 App Router guide, updated iOS 17 compatibility notes
v2.3.2 (2024-09-15) — Fixed manifest icon sizing references, improved code block syntax highlighting
v2.3.0 (2024-06-22) — Added Android Web App Manifest cross-platform guide