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:
- A regular ("any") icon: your logo, transparent background allowed, filling most of the canvas. Used where the browser doesn't apply a mask.
- 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:
-
purposevalues 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. -
sizesmust match the actual pixel size of the file. A mismatch can cause browsers to skip the icon or scale it badly. -
typeshould match the file format. Declaringimage/pngfor 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+jsonis 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_coloris used on the splash screen, so make sure your icon reads well on it.
A quick checklist
- [ ] Separate
anyandmaskableicons, each at 192 and 512 px - [ ] Maskable icon has a solid, full-bleed background
- [ ] Logo sits inside the central 80% circle
- [ ]
sizes,typeandsrcall 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.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.