What is a Maskable Icon? Simple Explanation for PWA Developers

## Quick Answer A maskable icon is a PWA icon with safe padding so Android can crop it into circles, squircles, rounded squares, and other launcher shapes without cutting off important artwork. ## Introduction If you have recently tested your newly built Progressive Web App on a modern Android device, you might have immediately noticed a glaring visual issue: your beautifully designed square logo suddenly has a harsh white background, or worse, Android heavily shrunk it down and forced it into a weird, tiny circular badge. This visually jarring experience happens because of "Adaptive Icons." To fix this properly, PWA developers must use something formally called a **Maskable Icon**. In this guide, we will deeply explain what maskable icons are, why they exist in the ecosystem, and how to seamlessly implement them. ## The Problem with Standard Icons Historically on the web, developers simply provided a transparent square image for their app icon. However, modern Android phone manufacturers (like Samsung, Google, Xiaomi, and OnePlus) all use vastly different visual design languages. Samsung might use squircles across its entire UI, Google might use perfect circles, and a custom launcher might use teardrops. When you blindly provide a standard transparent PNG to Android, the OS doesn't know how to intelligently fit your irregular shape into its uniform layout grid. Its crude fallback is usually to shrink your icon drastically and place it directly on top of a solid white circle. This immediately breaks the "native app" illusion, making your PWA look like a cheap web shortcut rather than a real application. ## The Maskable Icon Solution A maskable icon is an image fundamentally designed to be heavily and unpredictably cropped. It allows the operating system to apply a strict "mask" (a specific shape) over your image, confidently cutting away the edges to perfectly fit whatever shape the user's specific device prefers. Because you know the OS is going to crop the image, you must design it with a highly specific layout in mind: * **The Safe Zone:** All vitally important visual elements (your core logo, key text, primary branding) must be perfectly contained within a "safe zone" right in the dead center of the image. Specifically, everything must cleanly fit within a circle that has a radius of roughly 40% of the total image size. * **The Bleed Area:** The remaining outer edges of the image (the "bleed") should just be solid background color or extended, unimportant background patterns. You must assume this entire area will be completely deleted by the OS. * **No Transparency:** Critically, maskable icons should never have transparent backgrounds. They must be fully opaque from edge to edge. ## How to Declare a Maskable Icon Once you have successfully generated a maskable version of your logo, you must tell the browser about it in your `manifest.json`. You do this by adding a new object to your `"icons"` array and explicitly setting the `"purpose"` to `"maskable"`. ```json "icons": [ { "src": "/icon-512x512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" }, { "src": "/icon-maskable-512x512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" } ] ``` *Important Note: It is considered an absolute best practice to provide both a standard transparent icon (using `purpose: "any"`) and a dedicated maskable icon. The browser is smart enough to choose the best one for the current rendering context.* ## Conclusion Maskable icons are no longer optional if you actually care about the mobile install experience. By meticulously designing an icon with a proper safe zone and a solid background, and declaring it correctly in your manifest, you confidently ensure your PWA sits beautifully on any modern Android home screen, perfectly matching the expensive native apps right beside it.