PWA Icons: Maskable, Adaptive, and Everything in Between

Regular favicons sit in browser tabs. PWA icons do something different: they represent your app on a user's home screen, app drawer, task switcher, and splash screen. The requirements are stricter, the sizes are more numerous, and there is a concept called "maskable" that trips up nearly everyone the first time they encounter it.

If you have ever installed a PWA and seen your icon floating awkwardly inside a white circle on Android, or cropped so the edges are cut off, this guide explains why and how to fix it.

Why PWA Icons Are Different

A favicon lives in controlled environments. The browser tab has a known size and background. PWA icons live in the wild. Android might display your icon in a circle. Samsung's One UI might put it in a squircle. An older device might use a plain square. The operating system decides the shape, and your icon needs to survive all of them.

This is the fundamental difference. Favicons control their own frame. PWA icons do not. The OS applies a mask over your icon, clipping it to whatever shape it uses for all app icons on that device. Your job is to make sure nothing important gets clipped.

The Safe Zone Rule

Maskable icons must keep all meaningful content within the inner 80% of the image. That means 10% padding on every side. For a 512x512 icon, the safe zone is the inner 410x410 pixels, centered.

Why 80%? Because the most aggressive mask shape (a circle) clips roughly 10% from each edge. If your logo extends to the edges of the image, a circular mask will cut into it. The 80% safe zone guarantees your content survives every possible mask shape: circle, rounded square, squircle, teardrop, whatever the device manufacturer chose.

The remaining 20% (the outer padding) should be filled with your brand's background color or a solid color that matches your app's theme. Do not leave it transparent. The OS might fill transparent areas with white or black, and the result rarely looks intentional.

Icon Purpose Values

Each icon entry in your web manifest has a purpose field that tells the browser how the icon should be used. There are three possible values, and understanding when to use each one matters.

You can combine values like "any maskable", but I recommend against it. An icon designed to look good with a mask (padded content, solid background) looks wrong when rendered without one (too much empty space around the icon). Make separate images for any and maskable purposes.

Required Sizes

The web app manifest spec does not mandate specific sizes, but Android Chrome, the main consumer of PWA manifests, has clear preferences. Here are the sizes you should provide:

In practice, you can get away with just 192x192 and 512x512 for most cases. Chrome will downscale the 192 for smaller contexts and use the 512 for the splash screen. But if you want pixel-perfect rendering at every size, provide all of them. The difference between a downscaled icon and a hand-tuned one is visible at small sizes.

Manifest Configuration

Here is a complete manifest.json with both regular and maskable icons at the two most important sizes:

{
  "name": "My App",
  "short_name": "App",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#4a90d9",
  "icons": [
    {
      "src": "/icons/icon-192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icons/icon-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icons/icon-maskable-192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "maskable"
    },
    {
      "src": "/icons/icon-maskable-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}

Notice the separate files for any and maskable. The any versions have the icon filling the full canvas, possibly with a transparent background or a shaped background built into the image. The maskable versions have the icon centered in the safe zone with a solid background extending to all edges.

Creating Maskable Icons from Existing Logos

You cannot just take your regular favicon and declare it maskable. The process requires actual image editing. Start with a square canvas (512x512 works best). Fill the entire canvas with your brand color. Then place your logo centered on the canvas, scaled so it fits within the inner 80% (roughly 410x410 pixels within the 512 canvas). That is your maskable icon.

Common mistakes: using a transparent background (the OS will fill it with an unpredictable color), placing the logo too large (it gets clipped by circular masks), or using the same file for both any and maskable (the any version will have too much padding).

Monochrome Icons

The monochrome purpose is the least understood of the three. When an OS requests a monochrome icon, it takes only the alpha channel of your image. Opaque pixels become the foreground color (chosen by the OS), and transparent pixels show the background. Think of it like a stencil.

Android uses monochrome icons in notification badges and some themed icon contexts. In Android 13's themed icons feature, apps without a monochrome icon get a generic fallback, while apps with one get a nice tinted version that matches the user's wallpaper colors.

To create a monochrome icon, make a PNG where your logo shape is white (or any solid color) and everything else is transparent. The actual color does not matter since the OS discards it. Only the alpha channel counts.

Testing PWA Icons

Chrome DevTools has a manifest inspector under Application > Manifest that shows you which icons it found and flags problems. Use it. It will tell you if icons are missing, if sizes are wrong, or if the manifest has JSON errors.

For maskable icons specifically, load your image into maskable.app. It overlays different mask shapes (circle, squircle, rounded rectangle) so you can see exactly what gets clipped. If any part of your logo disappears under the circular mask, you need more padding.

The real test is installing the PWA on an actual Android device. Emulators work for basic checks, but device manufacturers customize icon rendering. A Samsung phone renders icons differently from a Pixel, which renders differently from a Xiaomi. If you can, test on at least two different Android devices.

What About iOS?

iOS does not use the web manifest for home screen icons. Safari reads the <link rel="apple-touch-icon"> tag from your HTML. The recommended size is 180x180 pixels. iOS applies its own rounded-rectangle mask and adds its own gloss effect (though the gloss has been disabled by default since iOS 7).

This means your manifest icons and your Apple Touch Icon are completely separate images serving separate platforms. You need both if you want your PWA to look right everywhere.

The good news is that Apple Touch Icons do not have a safe zone issue. iOS always applies the same rounded-rectangle mask, and it only clips a small amount from the corners. If your content is not in the extreme corners of the image, it will be fine.