Apple Touch Icon Documentation

Complete guide to generating, configuring, and deploying Apple touch icons and web app icons for all platforms.

🍎

Apple Touch Icons

Generate all required sizes for iPhone, iPad, and Mac Safari.

🌐

Multi-Platform

Android, Windows, macOS, iOS — all covered in one config.

⚡

Zero Config

Sensible defaults. Works out of the box with one command.

🔄

Auto-Conversion

Convert any image format to all required icon sizes.

📦

Build Tools

Plugins for Webpack, Vite, Rollup, and CLI support.

✔️

Validation

Check icons against Apple's latest specifications.

Quick Start

Get up and running in under 60 seconds. This guide walks you through generating a complete set of Apple touch icons from a single source image.

💡

Prerequisites: Node.js 18+ and npm, yarn, or pnpm installed. A source image (PNG, SVG, or WebP) at least 1024×1024 pixels recommended.

1

Install the package

Run the following command in your project directory:

bash

npm install @appletouch/icon-generator --save-dev

2

Place your source image

Place your icon source file (e.g., icon-source.png) in your project root or designated assets folder.

3

Generate icons

Run the CLI command to generate all icon sizes:

bash

npx appletouch generate --source ./icon-source.png --output ./public/icons

4

Link icons in HTML

Add the generated HTML link tags to your <head>:

                                    html
                                    
                                
<!-- Apple Touch Icons -->
<link rel="apple-touch-icon" href="/icons/apple-touch-icon.png">
<link rel="apple-touch-icon" sizes="152x152" href="/icons/apple-touch-icon-152x152.png">
<link rel="apple-touch-icon" sizes="180x180" href="/icons/apple-touch-icon-180x180.png">
<link rel="apple-touch-icon" sizes="167x167" href="/icons/apple-touch-icon-167x167.png">

✅

That's it! Your website now displays proper Apple touch icons on all iOS and macOS devices.

Installation

Install Apple Touch Icon Generator using your preferred package manager:

bash

npm install @appletouch/icon-generator

bash

yarn add @appletouch/icon-generator

bash

pnpm add @appletouch/icon-generator

                            html
                            
<script src="https://cdn.appletouch.io/v3/appletouch.min.js"></script>

System Requirements

Requirement	Minimum	Recommended
Node.js	18.0.0	20 LTS
npm	9.0	10.x
Source Image	512×512 PNG	1024×1024 PNG or SVG
Disk Space	10 MB	50 MB

Configuration

Customize icon generation behavior using a configuration file or programmatic API.

Configuration File

Create an appletouch.config.js file in your project root:

                        javascript — appletouch.config.js
                        
                    
module.exports = {
  source: './assets/icon-source.png',
  output: './public/icons',
  platforms: ['apple', 'android', 'web'],
  options: {
    quality: 95,
    trim: true,
    roundCorners: true,
    shadow: false,
    backgroundColor: 'transparent',
    generateHTML: true,
    generateManifest: true,
  },
  apple: {
    prefetch: true,
    precomposed: true,
    includeAllSizes: true,
  },
};

Configuration Options

source string required

Path to the source image file. Supports .png, .svg, .webp, and .ico formats.

output string optional

Output directory for generated icons. Defaults to ./icons.

platforms array optional

Target platforms. Available: apple, android, web, windows, firefox. Defaults to all.

options.quality number optional

Output image quality (1-100). Defaults to 95. Only applies to PNG/JPEG output.

options.trim boolean optional

Auto-trim transparent edges from source image. Defaults to false.

options.roundCorners boolean optional

Apply rounded corners to match Apple's icon guidelines. Defaults to false.

options.generateHTML boolean optional

Auto-generate <link> tags as a icons.html fragment. Defaults to true.

Supported Formats

Apple Touch Icon Generator supports a wide range of input and output formats to cover every platform requirement.

Input Formats

Format	Extension	Vector	Notes
PNG	`.png`	No	Recommended. Supports transparency.
SVG	`.svg`	Yes	Best quality for scaling.
WebP	`.webp`	No	Lossless mode recommended.
ICO	`.ico`	No	Legacy Windows format.

Output Formats

Platform	Format	File Pattern
iOS / macOS	PNG	`apple-touch-icon-{size}.png`
Android	PNG	`android-icon-{size}.png`
Web Favicon	ICO / PNG	`favicon.ico`, `favicon-32x32.png`
Windows	MSE / ICO	`mstile-{size}.png`
Firefox	PNG	`firefox-icon.png`

Icon Sizes

Here are all the icon sizes generated by default for each platform. You can customize these in your configuration.

Apple Touch Icon Sizes

Size	Device	File Name	Ratio
`180×180`	iPhone (iOS 7+)	apple-touch-icon.png	@3x
`167×167`	iPad Pro (12.9")	apple-touch-icon-167x167.png	@3x
`152×152`	iPad (iOS 7+)	apple-touch-icon-152x152.png	@2x
`120×120`	iPhone Retina	apple-touch-icon-120x120.png	@2x
`76×76`	iPad (legacy)	apple-touch-icon-76x76.png	@1x

⚠️

Important: Apple recommends providing icons at @2x and @3x resolution. If only one size is available, use 180×180 as it will be scaled down appropriately.

Android Icon Sizes

Size	Purpose	Density
`192×192`	Launcher icon	xdpi
`512×512`	Play Store	—

Web Favicon Sizes

Size	Purpose	Format
`16×16`	Tab favicon	ICO / PNG
`32×32`	Tab favicon (retina)	ICO / PNG
`180×180`	Apple touch fallback	PNG

Apple Specifications

Apple's Human Interface Guidelines specify precise requirements for touch icons. This section summarizes the key requirements.

Design Requirements

Do not apply rounded corners, drop shadows, or gloss effects — iOS adds these automatically.
Use a square canvas with equal dimensions.
Keep important visual elements within a central safe area to prevent clipping.
Use PNG format with 8-bit or 16-bit color depth.
Avoid transparency in the icon itself — use solid background colors.

HTML Link Tag Format

                        html
                        
                    
<!-- Single icon (auto-sized) -->
<link rel="apple-touch-icon" href="/apple-touch-icon.png">

<!-- Specific sizes -->
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon-180x180.png">
<link rel="apple-touch-icon" sizes="152x152" href="/apple-touch-icon-152x152.png">

<!-- Precomposed (no system effects) -->
<link rel="apple-touch-icon-precomposed" sizes="180x180" href="/apple-touch-icon-180x180.png">

💡

Tip: Use apple-touch-icon-precomposed if you've manually applied effects like rounded corners or shadows to your icon.

API Reference — Overview

The Apple Touch Icon API provides a RESTful interface for programmatic icon generation, conversion, and validation.

Base URL

https://api.appletouch.io/v3

Authentication

All API requests require an API key passed via the Authorization header:

http

Authorization: Bearer your-api-key-here

🔒

Security: Never expose your API key in client-side code. Store it in environment variables on your server.

Rate Limits

Plan	Requests / min	Max file size
Free	60	2 MB
Pro	600	10 MB
Enterprise	Unlimited	50 MB

Generate Icons

Generate a complete set of icons from a source image.

Endpoint

POST /generate

Request Body

                        json
                        
                    
{
  "source": "base64-encoded-image-data",
  "format": "png",
  "platforms": ["apple", "android", "web"],
  "options": {
    "quality": 95,
    "trim": true,
    "roundCorners": false
  }
}

Response

                        json
                        
                    
{
  "success": true,
  "jobId": "gen_abc123xyz",
  "icons": [
    {
      "name": "apple-touch-icon-180x180.png",
      "size": "180x180",
      "platform": "apple",
      "url": "https://cdn.appletouch.io/gen_abc123xyz/apple-touch-icon-180x180.png"
    },
    // ... more icons
  ],
  "html": "<link rel=\"apple-touch-icon\" ...>\n<link ...>",
  "manifest": "{\"icons\": [...] }"
}

Convert Icons

Convert an existing icon to different formats and sizes.

POST /convert

                        javascript
                        
                    
const response = await fetch('https://api.appletouch.io/v3/convert', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com/original-icon.png',
    targetSizes: [16, 32, 180, 512],
    format: 'png',
  }),
});

const result = await response.json();
console.log(result.icons); // Array of converted icons

Validate Icons

Check if your icons meet Apple's current specifications.

POST /validate

                        json
                        
                    
{
  "success": true,
  "valid": false,
  "issues": [
    {
      "severity": "warning",
      "message": "Icon has transparency — Apple recommends solid backgrounds",
      "file": "apple-touch-icon.png"
    },
    {
      "severity": "error",
      "message": "Missing required size: 180x180",
      "file": "N/A"
    }
  ],
  "score": 0.72
}

CLI Tool

Generate icons directly from the command line.

Commands

Command	Description
`appletouch generate [options]`	Generate icons from source image
`appletouch validate [path]`	Validate existing icon set
`appletouch convert [input] [output]`	Convert icon format/size
`appletouch init`	Create default config file
`appletouch watch [options]`	Watch for source changes and regenerate

Generate Options

Flag	Shorthand	Description
`--source, -s`	`-s`	Source image path
`--output, -o`	`-o`	Output directory
`--platforms, -p`	`-p`	Comma-separated platforms
`--config, -c`	`-c`	Config file path
`--watch, -w`	`-w`	Watch for changes
`--verbose, -v`	`-v`	Verbose output

Examples

                        bash
                        
                    
# Generate all icons
appletouch generate -s ./icon.png -o ./public/icons

# Apple only, with watch mode
appletouch generate -s ./icon.svg -o ./icons -p apple -w

# Validate existing icons
appletouch validate ./public/icons

# Initialize config
appletouch init

# Convert to specific sizes
appletouch convert ./icon.png ./output/ --sizes 16,32,180,512

Frequently Asked Questions

What is the minimum source image size? +

We recommend a minimum of 512×512 pixels for your source image. For best results across all platforms (including high-DPI displays), use 1024×1024 or larger. SVG files are ideal since they scale to any resolution without quality loss.

Do I need to apply rounded corners myself? +

No. Apple's iOS automatically applies rounded corners, drop shadows, and gloss effects to touch icons. You should provide a square icon with no effects applied. If you manually apply effects, use the precomposed variant of the link tag.

Can I use SVG as a source? +

Yes! SVG is actually the best source format because it scales to any resolution without quality loss. Our tool rasterizes SVGs at each required size automatically.

How do I handle icon updates? +

Simply run the generate command again with your updated source image. The tool will overwrite existing files. For production sites, add cache-busting query parameters or versioned filenames to ensure browsers fetch the updated icons.

Why isn't my touch icon showing up on iOS? +

Common issues include: (1) The icon file path is incorrect or inaccessible, (2) Missing the rel="apple-touch-icon" attribute, (3) The icon has a non-PNG format, (4) Server MIME type is incorrect. Use our validate command to check for common issues.

Troubleshooting

Common Errors

ERR_SOURCE_TOO_SMALL

Cause: Your source image is smaller than the smallest output size (16×16px).
Fix: Use a larger source image (minimum 512×512 recommended).

ERR_UNSUPPORTED_FORMAT

Cause: The source file format is not supported.
Fix: Convert your source to PNG, SVG, WebP, or ICO format.

ERR_OUTPUT_DIR_NOT_WRITABLE

Cause: The output directory doesn't exist or lacks write permissions.
Fix: Create the output directory manually or use --force flag.

💡

Still stuck? Check our GitHub Issues page or reach out to support at docs@appletouch.io.

Changelog

v3.2.0

January 15, 2025

NEW Added WebP output format support
NEW CLI watch mode for automatic regeneration
FIX Resolved SVG rasterization artifacts on high-DPI outputs
FIX Corrected iPad Pro 12.9" icon size from 167→192

v3.1.0

December 1, 2024

NEW Batch API endpoint for bulk icon generation
NEW Webhook support for async job notifications
BREAKING Minimum Node.js version bumped to 18
BUG Fixed memory leak in watch mode

v3.0.0

October 15, 2024

NEW Complete rewrite with improved performance (3x faster)
NEW New configuration file format (appletouch.config.js)
NEW Vite plugin support
BREAKING Removed deprecated --sizes flag, use config instead

License

Apple Touch Icon Generator is released under the MIT License.

text

MIT License

Copyright (c) 2025 Apple Touch Icon.png

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.