Maskable Icons Explained: Why Your PWA Icon Gets Cropped on Android

Quick answer: Android crops home-screen icons to whatever shape the launcher uses — circle, squircle, rounded square, teardrop. An icon declared "purpose": "maskable" opts into that system and must keep all its important content inside a centred circle covering the middle 80% of the image. An icon without that declaration is shown as-is, usually shrunk inside a white rounded square. Ship both, as separate files.

If your app's icon looks fine everywhere but shows up on Android with its edges chopped off — or floating tiny inside a white blob — this is the mechanism you're running into.

What Android is doing

Android launchers apply their own mask to every home-screen icon so that the whole grid looks consistent. One phone renders every icon as a circle, another as a squircle, a third as a rounded square. The launcher decides, not you and not the user.

For an installed web app, the browser has to hand the launcher something that survives that. It has two options, and which one it picks depends entirely on what your manifest says:

• If you provide a maskable icon, the browser passes it straight through and the launcher masks it. Your icon fills the entire tile, edge to edge, in whatever shape the device uses.
• If you don't, the browser can't safely crop your art — it might cut through your logo — so it plays it safe: it shrinks your icon and centres it on a generated white or light-grey background. That's the "tiny logo in a white circle" look, and it's why a perfectly good icon can end up looking unfinished next to native apps.

Neither outcome is a bug. The second one is the browser protecting you from the first.

The safe zone, precisely

A maskable icon is a full-bleed image where the outer edges are expendable. The guaranteed-visible region is a circle, centred, with a diameter of 80% of the image width.

For a 512×512 icon that means:

• Safe circle: 409px diameter, centred at (256, 256) — so a radius of about 205px.
• Everything outside that circle may be cropped on some devices.
• Your background must extend to all four edges, corner to corner. Transparency in the corners defeats the whole point.

In practice: take your normal icon artwork, put it on a solid or gradient background that fills the canvas, and scale the artwork down so it fits comfortably inside that central circle. If your logo currently touches the edges of your 512px icon, it needs roughly 20% padding added around it — meaning the mark itself occupies about 60–65% of the width, not 100%.

The most common mistake is treating a maskable icon as "my normal icon with rounded corners." A pre-rounded icon gets rounded again by the launcher mask, which clips the corners a second time and leaves visible flat edges where your rounding and the mask disagree. Maskable artwork should be a plain square with no rounding of its own — the launcher supplies the shape.

Declaring it in the manifest

The purpose field takes one or more space-separated values. The three that exist are any, maskable and monochrome.

{
  "name": "Your App",
  "short_name": "App",
  "icons": [
    {
      "src": "/icon-192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icon-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icon-maskable-192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "maskable"
    },
    {
      "src": "/icon-maskable-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}

Note that the maskable entries point at different files. This is the part people get wrong.

Don't write "purpose": "any maskable"

You'll see this shortcut everywhere, and it's a trap:

{ "src": "/icon-512.png", "sizes": "512x512", "purpose": "any maskable" }

That declaration tells the browser this single file is correct in both roles. It can't be, unless the artwork happens to satisfy both sets of constraints — which requires a design that looks intentional both full-bleed-and-cropped and shrunk-and-padded. Usually one of the two looks wrong: either the icon gets cropped on the home screen, or it looks like it has a huge empty margin in the app switcher and install prompt.

Two files. It costs you a few kilobytes.

What monochrome is for

The third purpose value supports themed icons, where the launcher recolours your icon to match the user's system palette:

{
  "src": "/icon-mono.png",
  "sizes": "512x512",
  "type": "image/png",
  "purpose": "monochrome"
}

A monochrome icon is treated as a stencil: the platform reads only the alpha channel and discards your colours entirely, filling the opaque pixels with a colour it chooses. So the artwork should be a solid, filled silhouette on a transparent background — no gradients, no colour, no thin details that vanish when flattened to a single tone. The same 80% safe zone applies, since it's masked like any other adaptive icon.

If you supply a full-colour icon with purpose: "monochrome", you'll get a solid blob in the shape of your icon's bounding box, because every non-transparent pixel counts.

Testing it before you ship

You don't need an Android device for the first pass:

1. Draw the safe circle. Open your 512px maskable icon in any editor and overlay a centred circle 409px across. Anything important outside it is at risk.
2. Check the four corners. They must be filled with background colour, not transparency and not rounding.
3. Chrome DevTools → Application → Manifest. It lists your declared icons, flags entries it can't fetch, and shows a maskable preview so you can see the crop.
4. Install it for real. On an Android device, install the app to the home screen and look at it next to native icons. Launcher masks vary enough between manufacturers that this is worth doing once.

For the manifest itself, the Checker reads a live site's manifest and reports which icons it declares, which purposes are covered and which ones fail to load — which is the quickest way to catch a maskable entry pointing at a path that doesn't exist.

A complete icon set in 2026

Putting it together, a site that covers every surface ships:

File	Size	Declared where	Purpose
favicon.ico	16/32/48 in one file	<link rel="icon">	Browser tabs, legacy fallback
favicon-32x32.png	32×32	<link rel="icon">	Retina tabs
apple-touch-icon.png	180×180	<link rel="apple-touch-icon">	iOS home screen
icon-192.png	192×192	manifest, purpose: any	Android, install prompt
icon-512.png	512×512	manifest, purpose: any	Splash screens, app switcher
icon-maskable-512.png	512×512	manifest, purpose: maskable	Android adaptive home screen
icon-mono.png (optional)	512×512	manifest, purpose: monochrome	Themed icons

The iOS touch icon has its own rule worth remembering here: iOS ignores transparency and fills it with black, and it applies its own rounding, so apple-touch-icon.png should be a full-bleed square with a solid background and no pre-rounded corners either. It's the same principle as maskable icons arrived at from a different direction.

The Generator and Converter export the standard set — .ico, the PNG sizes, the Apple touch icon and a manifest — from a single source image, and let you add background and padding so the same artwork can be re-exported with the extra margin a maskable variant needs.