PWA Manifest Icons, Explained

Last updated October 5, 2026

PWA
Web manifest
Maskable icons

When someone installs your web app, the browser takes its icon from the icons array in your web app manifest. This guide covers which sizes are required, what the purpose field does, how to design maskable icons and how iOS fits in.

Favicons versus manifest icons

A favicon is the small icon in a browser tab, declared with <link rel="icon"> tags. Manifest icons are the larger images used once your site behaves like an app: the home screen or desktop shortcut, the app launcher, the splash screen and the task switcher. They live in a JSON file linked from your page, usually called manifest.json or site.webmanifest. Most sites need both. The favicon guidelines cover the tab icons; this guide is about the manifest.

The icons array

Each entry in icons describes one image file. Four fields matter:

Field	Required	What it does
`src`	Yes	Path to the image. Relative paths resolve against the manifest's URL, not the page's.
`sizes`	No	Pixel dimensions such as `192x192`, or several separated by spaces. Use `any` for an SVG.
`type`	No	MIME type such as `image/png`. Lets the browser skip formats it cannot use without downloading them.
`purpose`	No	`any` (default), `maskable` or `monochrome`. Tells the browser how the icon may be displayed.

Fields of a manifest icon entry, as defined in the Web App Manifest specification.

Although sizes and type are optional, include them. The browser picks the best icon for each context by comparing sizes, and without them it may download every file or choose a poor match.

The 192 and 512 rule

Chromium-based browsers such as Chrome, Edge and Samsung Internet only offer to install a web app if the manifest includes, among other things, a 192 × 192 and a 512 × 512 icon. The other requirements are a name or short_name, a start_url, a display or display_override value, and prefer_related_applications left out or set to false. The site must also be served over HTTPS.

The 192 px icon is used for home screen and launcher shortcuts; the 512 px icon is used where more detail is needed, for example the splash screen Chrome on Android builds from your manifest. You can add more sizes, but these two are the minimum.

Purpose: any, maskable and monochrome

any

The default. The browser shows the image as is. On Android, a non-maskable icon may be shrunk and placed on a white circle or rounded square so it matches the other launcher icons, which often looks out of place.

maskable

A maskable icon is the web's version of an Android adaptive icon. You provide a full-bleed square with your background colour reaching every edge, and the platform cuts it into its own shape. Because the shape varies, the important part of the icon must stay inside a minimum safe zone: a centred circle whose radius is 40% of the icon's width. The outer 10% may be cropped on some platforms.

A maskable icon. The logo stays inside the circle; the background fills the whole square.

The circle covers 80% of the icon's width, so the logo ends up noticeably smaller than in a regular icon. That is the reason to provide separate files instead of one icon with "purpose": "any maskable". The specification allows combining purposes, but web.dev advises against it: a maskable design used as a regular icon looks over-padded, and a regular icon used as maskable gets clipped.

monochrome

A monochrome icon is used as a silhouette. The browser discards its colours and keeps only the alpha channel, then fills the shape with a single colour chosen by the system. It is intended for places where the platform wants a single-colour icon. Support for monochrome, and for purpose in general, varies between browsers, so treat it as an extra, not a replacement for the regular icons.

PNG or SVG?

PNG is the safe default for the 192 and 512 px icons because every browser that reads manifests can display it. An SVG with "sizes": "any" stays sharp at every size and is a good fit for a simple, flat monochrome icon. If you add one, keep the PNG entries as well, and give each file its type so browsers that cannot use SVG skip it without downloading it. Extra raster sizes such as 144 or 384 px are optional; when a size is missing, the browser scales one of the images you did provide.

A complete example

This manifest meets the installability rule, provides separate regular and maskable icons, and adds a monochrome SVG:

{
  "name": "Trail Notes",
  "short_name": "Trails",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#65ccb4",
  "icons": [
    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" },
    { "src": "/icons/maskable-192.png", "sizes": "192x192", "type": "image/png", "purpose": "maskable" },
    { "src": "/icons/maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" },
    { "src": "/icons/monochrome.svg", "sizes": "any", "type": "image/svg+xml", "purpose": "monochrome" }
  ]
}

Then link it from every page's <head>:

<link rel="manifest" href="/site.webmanifest">
<link rel="apple-touch-icon" href="/apple-touch-icon.png">

Where apple-touch-icon fits in

For years Safari on iOS ignored manifest icons and used only <link rel="apple-touch-icon"> for the Home Screen. Since Safari 15.4, iOS and iPadOS can also use manifest icons, but with two conditions: there is no apple-touch-icon in the page, and the icon's purpose is omitted or set to any. If an apple-touch-icon is present, it wins.

In practice, keeping a 180 × 180 apple-touch-icon is still the predictable option. iOS rounds its corners but does not treat it as maskable, so the image should be an opaque square with its own background and some padding around the logo. Transparent areas end up filled with a solid colour you did not choose.

Testing your icons

Chrome DevTools: open the Application panel and select Manifest. The Icons section shows each icon and has a "Show only the minimum safe area for maskable icons" option that crops your maskable icons to the safe zone. Errors such as missing sizes or unreachable files also appear here.
Maskable.app: a free tool that previews an icon in the different shapes Android launchers use, and includes an editor for adjusting padding and background colour.
A real device: install the app on an Android phone and add it to an iPhone Home Screen. Launchers differ, and a quick look on hardware catches problems the previews miss.

Common mistakes

Only a 512 px icon. Chromium needs both 192 and 512 before it offers installation.
A transparent PNG marked maskable. The transparent parts show as an unintended background once the shape is applied.
Wrong paths. src resolves relative to the manifest file, so a manifest in a subfolder breaks relative paths that work in HTML.
Mismatched sizes. Declaring 512x512 for a file that is actually a different size confuses the browser's selection.

The favicon generator produces the 192 and 512 px manifest icons, a site.webmanifest, the 180 px apple-touch-icon and the favicon files in one download. For native apps, use the app icon generator instead.

More guides

iOS App Icon Sizes – Every iPhone, iPad and App Store icon size, what each one is used for, and how Xcode’s single-size asset works.
Android Adaptive Icons – Foreground and background layers, the 108dp canvas, the 66dp safe zone and Android 13 themed icons.
iOS Dark & Tinted Icons – How dark and tinted Home Screen icons work, what to supply for each appearance and common mistakes.
macOS, watchOS & visionOS Icons – Icon shapes, sizes and layering for Apple platforms beyond iPhone and iPad.
App Icon Rejections – The icon problems that get builds rejected on the App Store and Google Play, and how to avoid them.