Maskable Android icons: manifest sizes that don't crop

10 min read

Your Android home screen icon looked perfect in the file you exported — then Android turned it into a circle and sliced off the corners of your logo. Nothing is broken. That crop is the feature.

On Android, the icon declared in site.webmanifest is not displayed exactly as supplied. Launchers place it behind a mask — a circle on one phone, a squircle, rounded square or teardrop on another — and the shape can change when the user switches launcher or theme. A maskable icon is an icon designed for that treatment: a full-bleed background that reaches every edge, with everything important kept inside a central safe zone that no reasonable mask will cut away.

This guide covers the whole chain: what belongs in the web app manifest, how maskable differs from any, the geometry of the safe zone, and how to test the result before your users see a decapitated logo.

Start with the mental model: Android displays a masked version, not your file

A desktop favicon is shown more or less as-is, inside a square tab. A home screen icon is closer to Android's adaptive icons for native apps: you supply the artwork, the system supplies the silhouette. You do not get to choose that silhouette, and you cannot opt out of it by exporting a rounder or squarer PNG.

That is the contract behind maskable icons: you promise the outer parts of the image are expendable — ideally just background — and the system keeps a defined central region visible in return. Run your logo edge to edge and the mask will crop it; keep the bargain and the same file survives a circle, a squircle and a rounded square alike.

A minimal, correct site.webmanifest

The manifest is a JSON file linked from every page's <head>:

<link rel="manifest" href="/site.webmanifest" />

A complete icon setup, with separate artwork for the two icon purposes discussed below, looks like this:

{
  "name": "Acme Notes",
  "short_name": "Acme",
  "start_url": "/",
  "scope": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#1d4ed8",
  "icons": [
    {
      "src": "/web-app-manifest-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/web-app-manifest-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/maskable-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "maskable"
    },
    {
      "src": "/maskable-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}

The fields that matter most for icons:

  • name and short_name — the full name appears on splash screens and in install dialogs; the short name sits under the home screen icon, where space is tight. Without short_name, the browser truncates name for you, rarely where you would choose.
  • icons — each entry needs a truthful src, sizes and type. Icon URLs resolve relative to the manifest file, so keep the icons next to site.webmanifest or use absolute paths.
  • background_color — fills the splash screen shown while the app starts. Match it to the maskable icon's background so icon and splash look like one object.
  • theme_color — tints browser chrome around the page. Independent of the icon, but worth keeping in the same brand family.
  • display — standalone opens the shortcut without the usual browser UI; fullscreen, minimal-ui and browser are the alternatives.
  • start_url and scope — where the shortcut lands and which URLs count as part of the app. They do not change the icon, but a shortcut that opens the wrong page undermines it.

Serve the file as application/manifest+json (or application/json) and make sure every src resolves. A manifest that parses but points at a 404 icon fails silently: the browser falls back to whatever it can find, often the Apple touch icon, which looks lost inside an Android circle.

Maskable vs any: purpose is a promise about the artwork

The purpose field tells the browser what the artwork was designed for. It is not a filter that changes how a given file is rendered so much as a promise the browser relies on when choosing which file to mask.

purpose: "any"

An any icon is a general-purpose icon: your logo as you drew it, possibly with transparency or its own padding, meant to be shown essentially intact where no aggressive mask is applied. If the system needs it on a home screen anyway, it typically scales the whole picture down and pads it onto a background — which is why non-maskable icons often appear small, floating on a white disc that clashes with dark launchers.

purpose: "maskable"

A maskable icon is designed to be masked. Its background is opaque and extends to all four edges — full bleed, no transparent corners, no built-in rounded corners — while the logo itself stays inside the safe zone. Because the background reaches the edges, the launcher can cut any shape out of it and the result still looks intentional: a solid brand-colored tile with your mark in the middle.

Declaring both

The robust setup declares both purposes, ideally as separate files, because the ideal artwork differs: the any version can keep transparency and tighter framing; the maskable version gets the full-bleed background and smaller, centered mark. Declaring one file as "purpose": "any maskable" is legal — generators that offer an "any and maskable" option emit the same PNGs once per purpose — but it only works if that one design satisfies both jobs. A transparent logo declared maskable is the classic failure: the mask crops it, and the corners become whatever the launcher puts behind them, often black or white.

Nor should you reuse the Apple touch icon as your maskable icon: at 180x180 it is too small for the 512 slot, and it already assumes iOS corner rounding, so Android masks a pre-masked icon and wastes most of the tile.

The safe zone, in actual pixels

The maskable specification defines a minimum safe zone: a circle centered in the icon whose diameter is 80% of the icon's width. Anything inside that circle is guaranteed to remain visible; anything outside it may be cut. Launchers are allowed to keep more than the safe zone, but designing for more is gambling on a particular phone.

For the two sizes you will actually ship, that means:

  • 512x512: the safe circle is about 410 pixels across, centered at (256, 256). Keep every essential pixel inside it, and let background alone fill the remaining ring and corners.
  • 192x192: the safe circle is about 154 pixels across, centered at (96, 96).

Note that the safe zone is a circle, not a square. A logo whose bounding box is 80% of the canvas still pokes its four corners outside the circle — a square inscribed in that circle sits exactly on it, so a square mark should be closer to 57% of the canvas width (410 ÷ √2 for the 512 icon) if its corners carry detail that matters. Round marks get more room; wide wordmarks get less. This is why text rarely survives as a maskable icon: shrunk into the safe circle, a wordmark becomes illegible long before it becomes safe. Use the symbol, the initial, the monogram.

A good starting point is a logo at roughly 60–70% of the canvas on a solid background, then a mask preview. EasyFaviconGenerator works this way in its Web app manifest section: "Add a plain background and margins" places your picture on an opaque background at a size you control, the Android Home and Splash previews show the masked result before you download, and you can set the name, short name, background and theme colors, display mode and icon purpose (maskable, any, or both) there. The package includes the 192x192 and 512x512 PNGs with the generated site.webmanifest.

A design recipe that does not get cropped

  1. Start square and large. Work from at least a 512x512 source, ideally the SVG or a larger square PNG, so the 512 export is a downscale, not an upscale.
  2. Fill the whole canvas with background. Brand color, subtle gradient or pattern — but opaque, edge to edge. No transparency, no pre-rounded corners; the launcher provides the corners.
  3. Shrink the mark into the safe circle. Center it, keep it within the central 80% circle, and be stricter with square or wide marks, as the geometry above shows.
  4. Check contrast against your own background. The mask keeps your background, so a low-contrast logo stays low-contrast on every phone.
  5. Preview masked, not square. Judge the icon as a circle and a squircle at small sizes. If it only works as a full square, it does not work.

Why you need both 192x192 and 512x512

Chrome looks for an icon of at least 192x192 for the home screen and a 512x512 icon for high-density displays, install dialogs and the splash screen. Provide only the 192 and the splash looks soft; provide only the 512 and browsers will scale it down, but declaring both costs two files and removes the guesswork. Always declare each file's real size — browsers pick icons based on what you claim, so a 512 file misdeclared as "sizes": "192x192" defeats the selection logic. And export both from the same artwork at the same framing, or the icon changes design depending on which file the launcher picked.

Testing before and after you publish

Most maskable failures are visible in thirty seconds of testing; they ship because nobody looked at a masked preview. Work through these checks:

  • Mask previews while designing. Look at the icon in a circle and a squircle, at home screen size, not zoomed in. In the generator, the Web app manifest section shows Android Home and Splash previews live as you adjust background, margins and purpose.
  • Chrome DevTools. On the deployed page, open DevTools → Application → Manifest. Chrome shows the parsed manifest and the icons it found; if the manifest is not listed at all, the <link rel="manifest"> tag is missing, misspelled or pointing at a 404.
  • Validate the boring details. Fetch site.webmanifest directly: it should return 200 with a JSON content type, and every icon src should return 200 too. Relative icon paths resolve against the manifest's URL, not the page's.
  • A real Android device, or the closest you have. Add the site to the home screen and look at the icon among real apps, on your actual wallpaper. Check the splash screen too: the icon centered on background_color should read as one designed screen, not a sticker on a mismatched field.
  • Reinstall after changes. Android caches icons aggressively, so remove the shortcut and add it again after deploying a new icon before concluding the new file is wrong.
  • Run a checker. The favicon checker fetches a deployed page, reports the manifest it found and previews the icons as Android home screen and splash screens — catching the "works locally, 404 in production" class of problem.

Troubleshooting the usual crop jobs

  • Logo corners are cut off. The mark extends beyond the safe circle. Shrink it, or increase the margins — with the generator, reduce the image size under "Add a plain background and margins" in the Web app manifest section.
  • Icon sits small on a white or black disc. The launcher only has an any (or transparent) icon to work with and is padding it. Add a true maskable icon with an opaque, full-bleed background.
  • Icon looks fine as a circle but loses its sides as a squircle. You designed for one mask. Design for the safe circle instead; every other shape keeps at least that much.
  • Splash screen icon is blurry. The 512x512 icon is missing, misdeclared, or was upscaled from a small source. Re-export from at least 512 pixels.
  • Old icon after an update. Caching, on the device and possibly at a CDN. Bump the file name or query version, then remove and re-add the home screen shortcut.
  • No install prompt, although the icons are right. Icons are only part of installability; the manifest alone does not make a site an installable PWA. Fix the icon problems above first, then look at the rest of the requirements rather than blaming the PNGs.

The short version

Declare 192x192 and 512x512 PNGs in site.webmanifest, give the maskable versions an opaque background that bleeds to every edge, keep the logo inside the central 80% circle — stricter for square and wide marks — and match background_color to it. Declare any and maskable separately when their artwork differs, and never let a transparent or pre-rounded icon carry the maskable promise. Then preview masked, test on a real home screen, and only trust the deployed result.

For the wider set of files that goes with these — SVG, PNG and ICO favicons and the Apple touch icon — see the guide to which favicon files you need.

All favicon articles