PWA Icons and Web App Manifest: A Complete Guide

What the Web App Manifest Is

The web app manifest is a small JSON file that tells the browser how your site should behave when installed. It defines the app name, the colors, how it launches, and, importantly, which icons to use on the home screen and splash screen.

Without a manifest, a browser treats your site as just a website. With a proper manifest and the right icons, the browser offers an install prompt and presents your site as a standalone app. The icons are what make that installed app feel real.

The Icon Sizes a PWA Needs

Two sizes do most of the heavy lifting for a progressive web app, with others filling in the gaps:

The 192 and 512 sizes are the baseline a manifest expects. Adding the 180 Apple touch icon rounds out support for iOS devices, which read it from a separate link tag rather than the manifest.

Maskable Icons and Safe Zones

Different devices crop icons into different shapes. A maskable icon accounts for this by keeping the logo inside a central safe zone with padding around it. When the system applies a circle or rounded square, nothing important is cut off.

Mark such an icon with a purpose of maskable in the manifest, and keep the key artwork within the middle 80 percent of the canvas. It is good practice to provide both a normal and a maskable version so each context gets the best fit.

A Working Manifest Example

Here is a minimal manifest that covers the essentials. Save it as site.webmanifest in your root and link to it from your HTML head.

{
  "name": "Your App Name",
  "short_name": "App",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#2563eb",
  "icons": [
    { "src": "/192x192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/512x512.png", "sizes": "512x512", "type": "image/png" },
    { "src": "/512x512.png", "sizes": "512x512",
      "type": "image/png", "purpose": "maskable" }
  ]
}

<link rel="manifest" href="/site.webmanifest" />
<link rel="apple-touch-icon" href="/180x180.png" />

Setup Checklist

• 192x192 and 512x512 PNG icons created
• A maskable version with safe-zone padding
• An Apple touch icon at 180x180 for iOS
• A site.webmanifest listing your icons and app details
• The manifest and Apple icon linked in your HTML head

Beyond Icons: Other Manifest Settings

Icons are the visible star of the manifest, but several other fields shape how your installed app looks and behaves. Knowing them helps you fine-tune the experience rather than settle for defaults.

• name and short_name. The full name appears on the install prompt, while the short name labels the icon on the home screen where space is tight.
• display. Set to standalone, this hides the browser address bar so the app feels native. Other values keep more of the browser interface.
• start_url. The page that opens when the app is launched. Usually your homepage, but it can be any entry point you choose.
• theme_color and background_color. These set the interface tint and the splash screen color, tying the launch experience to your brand.

You do not need every field to get started, but filling in the name, display, and colors alongside your icons produces a noticeably more polished installed app.

Making Your Site Installable

A manifest with icons is necessary, but a browser will only offer to install your site when a few conditions are met. Understanding them prevents the frustration of a correct-looking manifest that never triggers an install prompt.

First, your site generally needs to be served over HTTPS. Secure delivery is a baseline requirement for installable web apps. Second, the manifest must include the essentials: a name, a start URL, a display mode, and icons at the required sizes, including at least a 192 and a 512 pixel icon.

Many browsers also expect a service worker, a small script that lets the app load reliably and handle offline behavior. While a deep dive into service workers is beyond this guide, knowing one is part of the installable recipe explains why icons and a manifest alone sometimes do not produce an install prompt.

Testing Your PWA Setup

Once your manifest and icons are in place, verify everything works before relying on it. Browser developer tools make this straightforward.

• Open the Application panel. Most desktop browsers have a section that reads your manifest and lists the detected icons and settings.
• Run an audit. Built-in audits can check whether your site meets the installable criteria and point out what is missing.
• Install it on a phone. Add the site to a home screen and confirm the icon, name, and splash screen all look right.
• Check the maskable icon. A maskable preview tool shows how your icon will be cropped on different devices.

Common Manifest and Icon Errors

• Wrong icon paths. If the src values do not match the real file locations, the icons silently fail to load. Double-check each path.
• Missing required sizes. Without both a 192 and a 512 pixel icon, the install prompt may never appear.
• Logo clipped on Android. The maskable icon lacks safe-zone padding. Keep the artwork within the central area.
• Manifest not linked. The file exists but no link tag points to it. Add the manifest link to your HTML head.

FAQs