# How to create a Maskable Icon for Your APEX PWA

## Long story short

When installed on `Desktop`, a Progressive Web App (PWA) can have a transparent background app icon. But not on `Mobile` - it must have an opaque background there.

Transparent backdrop app icons have never been supported by `iOS`. All of your app icons, including PWAs, have a solid backdrop on your iPhone and iPad.

On `Android`, until a few years ago, developers were allowed to use app icons with a transparent background. App icons, however, have become more uniform in the most recent Android releases. On a specific home screen, each app's icon is the same size and form. And transparency is no longer supported.

Since `Android` is an open-source project, many vendors have their own version. And some of them use circle icons, some use square ones, some with round borders, etc. To handle this, browser vendors have introduced `Maskable icons`.

> More about Maskable icons here: [https://web.dev/maskable-icon/](https://web.dev/maskable-icon/)

## What are maskable and adaptive icons?

However, manufacturers, like Samsung, wanted to make all icons on a device the same shape to keep things consistent. Some manufacturers even wanted different shapes. To deal with the variety of requirements from manufacturers and devices, Android introduced “adaptive icons.” You supply an image with extra space around the edges, and Android will crop it to the correct shape.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1683307325998/94ce6a47-95cf-40ea-be8f-5188a162e79c.png align="center")

## What's the problem if Android icons are not maskable?

To look nicely integrated with operating systems that use masks, your PWA app icon should support masking. Masking-incompatible icons may seem cropped or smaller than planned. **Non-maskable icons** **on Android** **are centred within the circular mask and given a white backdrop**, which may clash with your icon.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1684834091450/5bcc4744-7c97-41c3-882d-aba92125c1d5.jpeg align="center")

The first image illustrates what the icon looks like on an Android device if the **Maskable** property is not added in the `Manifest` file. The second one is when the **Maskable** property is set.

If you didn't add a background to a transparent icon, Android would still add one. Most of the time, it would be white. Sometimes it would be black or some other darker background. A bit unpredictable.

[Maskable icons](https://www.w3.org/TR/appmanifest/#icon-masks) allow web developers to specify a full-bleed icon that will be cropped. It’s platform agnostic, so Windows could use them for tiles or iOS could use them for icons.

## How to create maskable icons

Maskable icons can be any size, and you can continue to use the same sizes that you’d use for normal transparent icons. <mark>But when designing the icon, ensure that important information is within a “safe zone” circle with a radius equal to 40% of the image’s size.</mark>

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1684834091450/5bcc4744-7c97-41c3-882d-aba92125c1d5.jpeg align="center")

There are a number of websites, offering icon generation. They transform your original image into various sizes and forms so that it can be used for your PWA.

> One example is [https://maskable.app/editor](https://maskable.app/editor).

You can always do that manually using Photoshop, Figma, Canva, Illustrator or any other image editor. I follow that approach.  
Oracle APEX also generates several different variations of your icon image file when you use the new Application icon functionality since the version `22.1`.

%[https://www.youtube.com/watch?v=09DBcT2kYpY] 

## Defining your manifest file

In Oracle APEX, the place to change your manifest file is `Shared Components` / `Progressive Web App` / `Custom Manifest`.

> Note that this functionality is available since APEX version `21.2`

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1684755539820/2629032d-8172-4aff-a1f1-19e6c69dc375.png align="center")

```json
{
  "name": "My PWA",
  "icons": [
    {
      "src": "#APP_FILES#icons/icon.png",
      "type": "image/png",
      "sizes": "512x512",
      "purpose": "maskable"
    }, 
    {
      "src": "#APP_FILES#icons/icon_transp.png",
      "type": "image/png",
      "sizes": "512x512"
    },
    {
      "src": "#APP_FILES#icons/icon.png",
      "type": "image/png",
      "sizes": "192x192",
      "purpose": "maskable"
    },
    {
      "src": "#APP_FILES#icons/icon.png",
      "type": "image/png",
      "sizes": "192x192"
    }
  ]
}
```

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1684834145991/261d9999-a241-4dbc-b075-481a0183c334.jpeg align="center")

In this example, the app manifest includes two icon entries: one for the regular app icon and another for the Maskable icon. Apart from this, I have used `icon_transp.png`, which is a transparent image for my Desktop users. The `sizes` attribute specifies the dimensions of the icons, and the `type` attribute indicates the image format.

The crucial part of enabling Maskable icons is the `purpose` property. For the regular app icon, the `purpose` is set to "any" to indicate that it can be used for any purpose, including as a mask. However, for the Maskable icon, the `purpose` is set to "maskable" explicitly, specifying that this icon is intended for adaptive shaping.

# **Follow me**

> *Like that post? Follow me on Twitter and LinkedIn!*

[![](https://cdn.hashnode.com/res/hashnode/image/upload/v1684769855346/4a53f86b-e5ba-4c0b-bf79-0397a8f3c054.png align="left")](https://twitter.com/plamen_9)

[![](https://cdn.hashnode.com/res/hashnode/image/upload/v1684769877594/82a5de36-0e62-48e9-94d7-81620e92018b.png align="left")](https://www.linkedin.com/in/plamen-mushkov/)