![Thomas Steiner](https://web.dev/images/authors/thomassteiner.jpg) Thomas Steiner [GitHub](https://github.com/tomayac) [LinkedIn](https://www.linkedin.com/in/thomassteinerlinkedin) [Mastodon](https://toot.cafe/@tomayac) [Bluesky](https://bsky.app/profile/tomayac.com) [Homepage](https://blog.tomayac.com/) ![Tiger Oakes](https://web.dev/images/authors/tigeroakes.jpg) Tiger Oakes [X](https://twitter.com/Not_Woods) [GitHub](https://github.com/NotWoods) [Homepage](https://tigeroakes.com/)

<br />

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.
![PWA icons in white circles on Android](https://web.dev/static/articles/maskable-icon/image/pwa-icons-white-circles-7fce0dc6ce82f.png) 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.
![PWA icons covering the entire circle on Android](https://web.dev/static/articles/maskable-icon/image/pwa-icons-covering-entir-011491639007f.png) 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](https://w3c.github.io/manifest/#icon-masks)
"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.
![Applications panel in DevTools displaying PWA icons with edges cropped](https://web.dev/static/articles/maskable-icon/image/applications-panel-devto-a75aad0ea167e.png) The Applications panel, showing cropped PWA icons.

To test your maskable icon with a variety of Android shapes, use Tiger Oakes'
[Maskable.app](https://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](https://maskable.app/editor). Upload your icon, adjust the
color and size, then export the image.
![Maskable.app Editor screenshot](https://web.dev/static/articles/maskable-icon/image/maskableapp-editor-scree-fdc82299dbabb.png) 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](https://web.dev/articles/add-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](https://web.dev/articles/add-manifest#icons).

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]
> **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](https://github.com/jpmedley).