Dev.to WebDev 🛠 Dev 👁 0 📖 4 min read

Maskable icons and the web app manifest: a how-to for PWA icons that don't get cropped

You've shipped a progressive web app, someone installs it on Android, and your logo appears shrunk inside a white circle or has its edges cut off. The browser tab favicon looked fine. The home screen icon didn't. The fi

You've shipped a progressive web app, someone installs it on Android, and your logo appears shrunk inside a white circle or has its edges cut off. The browser tab favicon looked fine. The home screen icon didn't.

The fix almost always lives in two places: your manifest.webmanifest (or manifest.json) and a properly padded maskable icon. This guide walks through both.

Why home screen icons get cropped

Android launchers display app icons in different shapes depending on the device and theme: circles, squircles, rounded squares, teardrops. To make web apps fit in, the browser applies a mask to your icon.

If your icon isn't designed for masking, one of two things happens:

  • The browser treats it as a regular icon and places it inside a plain background shape. That's the "logo on a white circle" look.
  • Or you've declared it maskable when it isn't padded, and the mask chops off the edges of your logo.

Maskable icons solve this by giving the browser a full-bleed image with your important content kept inside a central safe zone.

The safe zone rule

The maskable icon spec defines the safe zone as a circle centred in the icon with a radius of 40% of the icon width. Anything inside that circle survives every mask shape. Anything outside it might be cut.

In practical terms, for a 512 × 512 icon:

  • The safe circle has a diameter of about 410 pixels.
  • Your logo should fit comfortably inside that.
  • The area outside the safe zone should still be filled with background colour or pattern, not left transparent, because some masks show it.

A common mistake is exporting a transparent PNG with the logo filling the whole canvas. That works as a favicon but is the worst case for a maskable icon.

Step 1: Make two versions of your icon

You generally want both:

  1. A regular ("any") icon: your logo, transparent background allowed, filling most of the canvas. Used where the browser doesn't apply a mask.
  2. A maskable icon: solid background filling the canvas, logo scaled down to sit inside the safe zone.

Export each at 192 × 192 and 512 × 512 at minimum. Those two sizes cover the common install and splash screen cases.

Step 2: Declare them in the manifest

Here's a minimal, correct icons block:

{
  "name": "Example App",
  "short_name": "Example",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#1a73e8",
  "icons": [
    { "src": "/icon-192x192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" },
    { "src": "/icon-512x512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" },
    { "src": "/maskable-icon-192x192.png", "sizes": "192x192", "type": "image/png", "purpose": "maskable" },
    { "src": "/maskable-icon-512x512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
  ]
}

A few details that trip people up:

  • purpose values are space-separated. "any maskable" is valid and means the same image is used for both. Avoid it unless the image genuinely works both ways. A padded maskable icon looks too small when used as a regular icon, and a full-size logo gets cropped when masked.
  • sizes must match the actual pixel size of the file. A mismatch can cause browsers to skip the icon or scale it badly.
  • type should match the file format. Declaring image/png for an SVG or WebP file is a quiet source of bugs.
  • Paths are resolved relative to the manifest URL, not the page. If your manifest lives in a subfolder, check every src.

Step 3: Link the manifest from your HTML

<link rel="manifest" href="/manifest.webmanifest">
<meta name="theme-color" content="#1a73e8">

Keep your regular favicon tags as well. The manifest doesn't replace them, and iOS still relies on apple-touch-icon for home screen icons:

<link rel="icon" href="/favicon.ico" sizes="any">
<link rel="icon" href="/favicon.svg" type="image/svg+xml">
<link rel="apple-touch-icon" href="/apple-touch-icon.png">

Step 4: Test before you ship

Check a few things:

  • Open DevTools → Application → Manifest in a Chromium browser. It lists each icon, flags errors, and can show how maskable icons look with the safe zone applied.
  • Serve the manifest with a sensible content type. application/manifest+json is the standard one.
  • Clear and reinstall. Installed PWAs cache icons aggressively. After changing icons, uninstall the app and reinstall it to see the new version.
  • Check contrast against the background colour. background_color is used on the splash screen, so make sure your icon reads well on it.

A quick checklist

  • [ ] Separate any and maskable icons, each at 192 and 512 px
  • [ ] Maskable icon has a solid, full-bleed background
  • [ ] Logo sits inside the central 80% circle
  • [ ] sizes, type and src all match the real files
  • [ ] Manifest linked in <head>, favicon and apple-touch-icon still present
  • [ ] Tested by reinstalling, not just reloading

Tools that speed this up

We built Favicon.now around this workflow. You can generate a favicon from an image, SVG, text or emoji and download an install-ready ZIP that includes maskable PWA icons alongside the ICO, PNG, SVG and Apple touch files, with the matching manifest and HTML code. If you already have a manifest, the Manifest validator checks your PWA icon declarations, and the Manifest generator builds both ordinary and maskable declarations for you. The Check a live site tool then shows what a deployed site actually serves.

The takeaway

Cropped PWA icons are almost never a browser bug. Give the browser a padded, full-bleed maskable icon, declare it separately from your regular icon, make sure every manifest field matches the real file, and reinstall to test.

📰 Read the original article on Dev.to WebDev

Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.