Maskable Icon: Safe Zones and the purpose Field
A maskable icon is a PWA icon drawn to fill its entire square so the platform can crop it to whatever shape it uses — circle, squircle, rounded square — without cutting anything important. You keep the logo inside a safe zone of roughly the inner 80 percent, a centred circle whose diameter is 80 percent of the icon's width, and let the background bleed to all four edges. You declare it in the web app manifest with "purpose": "maskable".
The problem it solves
Android launchers apply a shape mask to every app icon so that a home screen looks consistent, and the shape varies by device and by launcher — circle on one, squircle on another, rounded square on a third. A normal web icon handed to that system gets shrunk into a white rounded box, or worse, cropped through the logo.
A maskable icon is authored for that crop. The artwork extends to every edge, and the meaningful content sits well inside, so any of those masks lands on background rather than on the mark. It is the same idea as Android's adaptive icons, expressed as one image plus a declaration.
Declaring one
"icons": [
{ "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" },
{
"src": "/icon-maskable-512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "maskable"
}
]Ship both. The default-purpose icon is used where the platform does not crop; the maskable one is used where it does.
Safe zone by icon size
| Icon size | Safe-zone diameter (80%) | Clear margin per edge |
|---|---|---|
| 192x192 | 154px | 19px |
| 384x384 | 307px | 38px |
| 512x512 | 410px | 51px |
Maskable icon FAQ
Can I just add padding to my existing icon?
That is most of the job, but the padding has to be filled background rather than transparency. A transparent margin gives the launcher nothing to crop into and you end up with a small logo on a plain white tile.
How do I check the safe zone is right?
Overlay a centred circle at 80 percent of the icon's width and confirm nothing you care about crosses it, then install the PWA on an Android device and look at the launcher. Chromium DevTools also previews manifest icons under the Application panel.
Does iOS use maskable icons?
No. iOS takes the Home Screen icon from the apple-touch-icon link and applies its own fixed rounded-corner mask, so the maskable purpose has no effect there.