Web App Manifest Icons Explained
A web app manifest is a small text file that tells a browser how your site should look when it's installed like an app. The icons are one part of it.
MDN defines it as a JSON text file that provides information about a web application1. JSON is a plain-text format of names and values. The most common use is giving a browser what it needs to install a progressive web app, such as the app's name and icon1.
How the page finds it
A manifest is deployed with a link element in the head of the page1. It looks like <link rel="manifest" href="/manifest.json">.
MDN says the .webmanifest extension is in the specification, and browsers generally support other appropriate extensions such as .json1.
The icons member
The icons member specifies one or more image files that represent your web application2. It's a list. Each entry can have these properties:
- src: the path to the image. It's the only required property. A relative path is resolved relative to the manifest file's address2.
- sizes: written as width x height in pixels, such as 48x48. Several sizes are separated by spaces. MDN recommends listing the exact sizes for raster formats like PNG, and says you can use any for vector formats like SVG2.
- type: the MIME type, for example image/png. If you leave it out, browsers typically infer it from the file extension2.
- purpose: tells the browser what the icon is meant for. If omitted, the browser can use the icon for any purpose2.
One entry can be as short as { "src": "icon-192.png", "sizes": "192x192", "type": "image/png" }2.
Which sizes to list
The honest answer is that the operating system decides. MDN says the sizes at which an icon is displayed depend on the operating system and may change over time3. Its guide advises designing the image at least 1024x1024 pixels, or scalable to that size, since that's the largest size an icon may be shown at3.
MDN's own examples list several PNG files of different sizes, and another that mixes a WebP file, an ICO file and a scalable SVG3. For the exact sizes a platform wants, MDN points to each platform's own guidance: Microsoft, Android and Apple. Check those pages for current numbers.
Maskable icons
Some systems cut icons into a shape, such as a circle. MDN says icons that don't support masking may appear cropped or smaller than expected3.
A maskable icon is designed with masks and a safe zone in mind, so anything outside the safe zone can be ignored2. MDN defines the safe zone as a circle whose diameter is 80% of the icon's smallest dimension. It also says to give a maskable icon an opaque background colour that fills the whole icon area3.
To mark one, set the purpose to maskable. Add "purpose": "maskable" to that icon's entry2.
Not the same as a favicon
MDN says the app icon isn't the same as the favicon shown in places like the address bar. A site can have both3. The tab icon is set with a link tag, as shown in the page on adding tab icons. iPhones and iPads use their own tag, covered on the iPhone home screen guide.
Sources used
- Web application manifest, MDN Web Docs
- icons - Web app manifest, MDN Web Docs
- Define your app icons, MDN Web Docs