Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 37 ยท Web App Manifest

Manifest Icons: Sizes, Purposes and Maskable

Choose the right PWA icon sizes, understand the purpose values any, maskable and monochrome, design a safe zone, and add the iOS apple-touch-icon.

An installed PWA is judged by its icon. It appears on the home screen, in the app launcher, on the splash screen and in task switchers, on devices of every density and shape. The manifest's icons array tells the browser which images to use. Get it right and your app looks native everywhere. Get it wrong and you may see a blurry logo, a tiny icon floating in a white circle, or a missing install option.

The icons array

Each entry has a src, a sizes string and a type. A purpose is optional.

JSON
{
  "icons": [
    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" },
    { "src": "/icons/icon-maskable-512.png", "sizes": "512x512",
      "type": "image/png", "purpose": "maskable" },
    { "src": "/icons/icon.svg", "sizes": "any", "type": "image/svg+xml" }
  ]
}
  • sizes is a space-separated list of WxH pixel sizes, or any for scalable images such as SVG. You can list several sizes for one file only when it is a multi-size format like .ico.
  • type is the MIME type. It lets the browser skip formats it does not support without downloading them.
  • src is resolved against the manifest URL.

Which sizes do you need?

The practical minimum for Chromium installability is 192 x 192 and 512 x 512 PNG icons. The 192 icon is used for launchers; the 512 icon is used for splash screens and stores, and the browser scales between sizes as needed.

Many teams also add:

Size Where it helps
48, 72, 96, 144 px Older Android launchers and density buckets
180 px iOS apple-touch-icon
512 px maskable Android adaptive icons
SVG Crisp favicon and scalable use

Don't ship twelve icons if you can't maintain them. Start with 192, 512, a maskable 512 and a favicon, then add more only when you see a problem.

Purpose: any, maskable, monochrome

The purpose member says how an icon may be used. It takes a space-separated list. The default is any.

  • any: use as is, with transparent corners allowed. Good for desktop windows and the browser UI.
  • maskable: the operating system may crop the icon into a circle, squircle or rounded square (Android adaptive icons). The artwork must fill the entire square, with the important part inside a safe zone.
  • monochrome: a single-color glyph the OS can tint (for themed icons on newer Android). Optional.

Do not combine any maskable in one entry. A maskable icon with a full-bleed background looks strange when used as any, and a transparent any icon gets an ugly background when masked. Provide separate files.

The maskable safe zone

When the OS masks your icon, it can cut away the outer area. Keep all important content (logo, text) inside a circle whose diameter is 80% of the icon size, centered. For a 512 px icon that is a 410 px circle. Fill the rest with your brand color so cropping shows color, not transparency.

flowchart TD
  A["Full icon 512x512: fill with brand color"] --> B["Safe zone: central circle, 80% diameter"]
  B --> C["Logo lives here"]
  A --> D["Outer 10% on each side may be cropped by the OS"]

Design the background to the edge, but keep the logo in the center circle.

You can see the effect with the following SVG experiment. The dashed circle is the safe zone and the three shapes show what different masks might keep.

Preview a maskable safe zone

Creating the files

You can export PNGs from any design tool, or generate them from one SVG. Many online maskable-icon editors let you check the safe zone visually. For repeated builds, a script or a build plugin can resize a single 1024 px source into every size.

Keep file sizes small: icons are downloaded on install and cached. Optimize PNGs, and prefer SVG for simple logos when the browser accepts it (note that not every platform renders SVG manifest icons for launchers, so keep the PNGs).

Apple and the favicon

Safari on iOS does not use the manifest icons for the home screen in older versions and prefers a dedicated link. Add it to your HTML:

HTML
<link rel="apple-touch-icon" href="/icons/icon-180.png">
<link rel="icon" href="/icons/icon.svg" type="image/svg+xml">
<link rel="icon" href="/favicon.ico" sizes="32x32">

The apple-touch-icon should be 180 x 180 px, opaque and without rounded corners (iOS adds them). A transparent background becomes black on iOS, so fill it.

Choosing the right icon programmatically

Browsers pick the closest icon for the size they need. You can explore that logic. The stand-in below picks an icon for a requested size, preferring the smallest icon that is at least as large (so it is scaled down, not up) and respecting the purpose.

JS Stand-in: pick an icon like a launcher

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Testing your icons

In Chrome DevTools, open Application > Manifest. Under "Icons" you see each image with its size. The Show only the minimum safe area for maskable icons checkbox overlays the safe zone so you can judge your artwork. Installability problems about icons also show up in that panel.

If the browser cannot download an icon (wrong path, wrong type, 404) it silently moves on. Always open each icon URL in the browser once to make sure it loads.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which two PNG sizes are the practical minimum for installability in Chromium?

    Chromium expects a 192 px and a 512 px icon in the manifest.
  2. 2. What is a maskable icon?

    Maskable icons have full-bleed artwork and a central safe zone so any mask shape works.
  3. 3. How large is the safe zone of a maskable icon?

    Keep important content inside the central circle of 80% diameter.
  4. 4. Why add an apple-touch-icon link?

    Safari uses apple-touch-icon, 180x180, opaque, for the iOS home screen.

Summary

  • List at least 192 and 512 px PNG icons in the manifest, with correct type.
  • Add a separate maskable icon with full-bleed artwork and content inside the 80% safe zone.
  • Don't mix any and maskable in one entry.
  • Provide a 180 px apple-touch-icon for iOS and an SVG/ICO favicon.
  • Check every icon in DevTools and by opening its URL.

Next: Display Modes, Colors and Orientation