Adaptive icon support in PWAs with maskable icons

Thomas Steiner

Tiger Oakes

If you've installed a Progressive Web App (PWA) on a recent Android phone, you might notice the app's icon has a white background. Android 8.0 introduced adaptive icons, which display app icons in a variety of shapes across device models. Icons that don't use this format have white backgrounds.

Transparent PWA icons appear inside white circles on Android.

Maskable icons are a new icon format for Chrome and Firefox that lets your Progressive Web App use adaptive icons and gives you more control over your icon's appearance.

Maskable icons cover the entire circle instead.

Are my current icons ready?

Because maskable icons need to support a variety of shapes, you need to supply an opaque image with some padding that the browser can crop to the required shape and size for any browser or platform.

Different platform-specific icon shapes.

The maskable icon specification includes a standardized "minimum safe zone" that all platforms respect. The important parts of your icon, such as your logo, must be within a circular area in the center of the icon with a radius equal to 40% of the icon width. The outer 10% edge might be cropped on some platforms.

You can check which parts of your icons are within the safe zone using Chrome DevTools. With your Progressive Web App open, launch DevTools and navigate to the Application panel. In the Icons section, you can choose to Show only the minimum safe area for maskable icons. This trims your icons so only the safe area is visible. If your logo is visible within this safe area, your icon is ready.

The Applications panel, showing cropped PWA icons.

To test your maskable icon with a variety of Android shapes, use Tiger Oakes' Maskable.app. Open an icon, and Maskable.app lets you try various shapes and sizes and share the preview with your team.

How do I adopt maskable icons?

To create a maskable icon based on an existing icon, you can use the Maskable.app Editor. Upload your icon, adjust the color and size, then export the image.

Creating icons in the Maskable.app Editor.

After you create a maskable icon and test it in DevTools, you need to update your web app manifest to point to the new asset. The web app manifest provides information about your web app in a JSON file, and includes an icons array.

The purpose field tells the browser how your icon should be used. By default, icons have a purpose of "any". In Android, these icons are resized on a white background.

{
  …
  "icons": [
    …
    {
      "src": "path/to/regular_icon.png",
      "sizes": "196x196",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "path/to/maskable_icon.png",
      "sizes": "196x196",
      "type": "image/png",
      "purpose": "maskable" // <-- New property value `"maskable"`
    },
    …
  ],
  …
}

To make an icon maskable, set its purpose value to "maskable" to indicate that it should be used with icon masks. This removes the white background and gives you more control over the icon's appearance. You can also specify multiple space-separated purposes (for example, "any maskable") if you want your maskable icon to be used without a mask on other devices.

Caution: We don't recommend using multiple purposes for maskable icons. Using maskable icons as any icons adds unnecessary padding, making the core icon content smaller. We recommend designing any icons like your site's favicons, with transparent regions and no extra padding.

Acknowledgements

This page was reviewed by Joe Medley.