Why a PWA app icon shouldn't have a purpose set to 'any maskable'
Tags: pwa, javascript, webdev, beginners
Published: 2022-01-06 04:54:38

A Progressive Web App requires a [web app manifest](https://progressier.com/features/no-code-web-app-manifest), a JSON file that contains the details of your app (things like the name and icons of your PWA). 

An app manifest must have an [array of icons](https://developer.mozilla.org/en-US/docs/Web/Manifest/icons). Each of these icons has a purpose set to either `monochrome`, `any` or` maskable` or a combination of these three values.

## Why is "any maskable" discouraged by Chrome?
Lately, I've noticed quite a few PWA app manifests displaying a warning that until mid-2021 didn't exist (those created with [Progressier](https://progressier.com) always work great though!): 

> _Declaring an icon with purpose "any maskable" is discouraged. It is likely to look incorrect on some platforms due to too much or too little padding._
```
{
  …
  "icons": [
    {
      "src": "icon2.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any maskable" // <-- triggers the warning
    }
  ],
  …
}
```

In this article, I'll show you exactly what Chrome means with that warning, but first I must explain what `maskable icons` are and why they exist.

## What are `maskable` icons?
Until a few years ago, app icons on Android could have a transparent background and use any shape they wanted. And that frankly made your home screen quite messy. Look at that Samsung Galaxy Note 4 from 2014:

![Home screen of a Samsung Galaxy Note 4 from 2014](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/tg3zekcw3ih33dni1fs3.jpg)

Since then, smartphone vendors — probably in an effort to emulate iOS — standardized app icons. On a given home screen, every app icon has the same size and shape.

![Samsung Galaxy Note S21 vs Google Pixel 6 have different icon styles](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ntlr11okhwkitahxeb4y.jpg)
_Samsung Galaxy Note S21+ (Square icons with rounded corners) vs Google Pixel 6 (circular icons)_

_Thankfully_, the W3C folks came up with the [maskable icon](https://www.w3.org/TR/appmanifest/#icon-masks) feature. A maskable icon is one that has a safe zone that is cropped so that the icon can be displayed within a variety of shapes and occupy the entire space available.

(I say "_thankfully_" because just imagine the mess it would have become if developers had to provide a different icon for each possible shape.)

## Difference between `any` and `maskable`

Here is how a Android home screen renders the same PNG image with the purpose set to `maskable` (left) and set to `any` (right)
![Purpose set to maskable vs any](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/7hoimei1exupph3jyg85.jpg)

## So why no `any maskable` icons?
In short, it's because it's very difficult to create an app icon that can be used as-is and as a mask. You'll almost always either have too much or too little padding.

## The perfect solution
Use [Progressier](https://progressier.com) to have icons perfectly sized automatically. Else to do it manually, create two 512x512 icons, one with the purpose `maskable`, and the other with the purpose `any`. Make your `maskable` icon fit the entirety of the area. And give your `any` icon 40 pixels of padding and 20% of border-radius (so that it looks great on all macOS versions).

```
{
  …
  "icons": [
    {
      "src": "icon2.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "icon2.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    },
  ],
  …
}
```

## Where do my PWA icons show?
Different platforms will use either of the two icons.
- On **Android**, the **home screen** and **install prompt** use the icon with the purpose `maskable`
- The **splash screen** generated by recent **Android phones** (post 2020) uses the icon with the purpose `maskable`
- Older or low-end **Android phones** may have a **splash screen** generated from the icon with the purpose `any` instead.
- **Chrome OS** uses the icon with the purpose `maskable`
- **Windows** uses the icon with the purpose `any` with all browsers, as it does not enforce any particular icon shapes
- **macOS Ventura** or lower uses the icon with the purpose `any`
- **macOS Sonoma** or higher uses the icon with the purpose `maskable`
- **iOS** requires an extra set of icons set with the `apple-touch-icon` (home screen icon)  and `apple-touch-startup-image` meta tags (splash screen)