Icons and Maskable Icons
The icons array
Section titled “The icons array”The manifest icons field is an array of image objects. The browser picks the most appropriate size for each context: install dialog, home screen, splash screen, and app switcher.
{ "icons": [ { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" }, { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" } ]}Each entry has three properties:
| Property | Description |
|---|---|
src | Path to the image file (absolute or relative to the manifest) |
sizes | Space-separated list of WxH dimensions the file covers |
type | MIME type — "image/png", "image/svg+xml", etc. |
purpose | Optional: "any", "maskable", or "any maskable" |
Minimum required sizes
Section titled “Minimum required sizes”Chrome and other Chromium browsers require at least a 192 x 192 icon to show the install prompt, and a 512 x 512 icon for the splash screen. Always include both.
SVG icons can cover all sizes with a single entry:
{ "src": "/icons/icon.svg", "sizes": "any", "type": "image/svg+xml" }Maskable icons
Section titled “Maskable icons”Android 8 (Oreo) and later use adaptive icons — the OS clips the icon into a shape (circle, squircle, teardrop, etc.) that matches the device’s theme. A standard icon placed inside that mask may have its edges cut off.
A maskable icon is designed with all important artwork inside a central safe zone that is guaranteed to remain visible regardless of the mask shape. The safe zone is a circle whose diameter is 80 % of the shortest edge of the image.
flowchart TB
subgraph icon ["512 x 512 icon canvas"]
subgraph safe ["Safe zone (80% circle — always visible)"]
Logo["Logo / artwork here"]
end
BleedArea["Bleed area — may be clipped by OS mask"]
end Declare a maskable icon by setting "purpose": "maskable":
{ "src": "/icons/icon-512-maskable.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable"}You can also serve one file for both purposes:
{ "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any maskable"}However, that only works if your artwork genuinely respects the safe zone. In most cases, provide two separate files: one regular icon (purpose: "any") and one designed specifically for masking (purpose: "maskable").
Generating icons
Section titled “Generating icons”Use Maskable.app to preview how your icon looks inside common mask shapes. PWA Asset Generator can batch-generate all required sizes from a single SVG source.
A recommended icon set:
[ { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" }, { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" }, { "src": "/icons/icon-192-maskable.png", "sizes": "192x192", "type": "image/png", "purpose": "maskable" }, { "src": "/icons/icon-512-maskable.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }]Trade-offs
Section titled “Trade-offs”| Option | Benefit | Cost |
|---|---|---|
| Make a maskable icon separate from the regular icon | Icon does not get clipped oddly on Android’s circular crop | Requires designing and exporting an extra icon file |
| Use one icon file for every purpose | Fewer files to manage, simpler upkeep | Risk of a distorted crop on platforms that expect a maskable safe zone |
Common mistakes
Section titled “Common mistakes”- Not including a
purpose: "maskable"icon at all, so Android crops the regular icon into a circle and clips the logo. - Designing the logo to the full edge of the 512x512 canvas without leaving the central 80% safe zone the maskable icon spec requires.
- Only providing one icon size (e.g. 192x192), forcing devices that need higher resolution to upscale it until it looks blurry.
Squoosh designs a dedicated maskable icon for Android with the safe zone respected per spec, so the logo is not clipped when it is cropped into a circle (source on GitHub — it ships an icon-large-maskable.png asset). Maskable.app is the standard preview tool PWA developers use to check the safe zone before shipping an icon — it is a community tool maintained by Tiger Oakes, not an official Google product.