Why PWA icons can look wrong on Android
If you've installed a Progressive Web App (PWA) on a recent Android device, you may have noticed its icon sits on a white background. Android 8.0 introduced adaptive icons, which render app icons in various shapes depending on the device. Icons that aren't designed for this format get a white backing instead.
The maskable icon format
Maskable icons are an icon format supported by Chrome and Firefox that let PWAs use adaptive icons. They give you control over how your icon appears when the platform applies its own mask.
Because maskable icons must accommodate a range of shapes, you need to supply an opaque image with padding around the important content. The browser crops this image to fit the shape and size required by the platform.
The maskable icon specification defines a standardized minimum safe zone. Your logo and other essential elements must fit within a circular area in the center of the icon, with a radius equal to 40% of the icon width. The outer 10% of the edge may be cropped on some platforms.
Verifying your current icons
Chrome DevTools can help you check whether your icons respect the safe zone. Open your PWA, launch DevTools, and go to the Application panel. In the Icons section, select Show only the minimum safe area for maskable icons. This trims the icon down to the safe area; if your logo is still visible, the icon is ready.
To preview how your maskable icon will look across Android shapes, try Maskable.app. You can upload an icon and test it against various shapes and sizes before sharing previews with your team.
Adding maskable support to your manifest
If you need to create a maskable icon from an existing one, the Maskable.app Editor lets you upload an icon, tweak the color and size, and export the result.
Once you have your icon and have confirmed it in DevTools, update the web app manifest to point to the new asset. The manifest's icons array defines how your app appears on a device.
Each icon entry includes a purpose field that tells the browser how to use the icon. By default, purpose is "any", which means Android resizes the icon on a white background.
Set the purpose value to "maskable" to signal that the icon should be used with the platform's masks. This removes the white background and gives you more control over the app icon's appearance. You can also specify multiple purposes as space-separated values (for example, "any maskable") to let the maskable icon be used without a mask on other devices.
