The Web App Manifest, Explained: Icons, Theme Color and PWA Installs
What site.webmanifest actually does, which fields matter for icons, and how to get it right.
· 5 min read
Quick answer: site.webmanifest is a JSON file that tells Chrome and Android how to treat your site as an installable app — its icons array (192×192 and 512×512 matter most), theme_color, background_color, and display mode together determine whether an "install app" prompt appears at all and what the installed app looks like.
A lot of favicon confusion traces back to one file most people copy-paste without reading: site.webmanifest. It looks like just another place to list icon sizes, but it's doing something more specific than that — it's the signal browsers use to decide whether your site qualifies as an installable app in the first place. Get it wrong and you don't get a slightly-worse icon, you get no install prompt at all.
A minimal real example
{
"name": "Favicon Tools",
"short_name": "Favicon",
"icons": [
{
"src": "/icon-192.png",
"sizes": "192x192",
"type": "image/png",
"purpose": "any"
},
{
"src": "/icon-512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "maskable"
}
],
"theme_color": "#0f172a",
"background_color": "#ffffff",
"display": "standalone"
}
Linked from HTML with a single tag in <head>:
<link rel="manifest" href="/site.webmanifest">
Every field here has a specific, testable effect. Here's what each one actually does.
name and short_name
name is the full app name, used in install prompts and app info screens where there's room for a longer string. short_name is what actually gets shown under the icon on a home screen or in an app switcher, where space is tight — most launchers truncate name in those spots, so short_name exists specifically to give you control over what fits. If you only set name, expect it to get cut off somewhere you didn't choose.
icons: the array that matters most
This is the field most directly tied to what people mean by "app icon." The two sizes that actually matter are 192×192 and 512×512:
- 192×192 is the standard size Android uses for the home-screen and launcher icon itself.
- 512×512 is used for splash screens shown while the installed app is loading, and for larger contexts like app switchers.
The purpose field controls how Android is allowed to use the icon. purpose: "any" means render it as-is. purpose: "maskable" tells Android it's safe to crop the icon into its adaptive icon shapes — circle, squircle, rounded square, whatever the device theme uses — without clipping anything important. A maskable icon needs enough padding around the subject that cropping to any of those shapes doesn't cut off a logo or letter. Without a maskable variant, Android will still adapt the icon, but it may clip content that was drawn edge-to-edge.
These are manifest-only sizes — they're separate from the browser-tab favicon and from the Apple touch icon, which come from entirely different declarations. Our comparison of favicon, touch icon, and app icon covers how all three fit together, and the size guide lists every size a complete set needs.
theme_color
theme_color tints the browser chrome around the page on mobile — the address bar area in Chrome for Android, for instance — and it also colors the title bar of an installed PWA once it's running standalone. It's a small detail, but it's the difference between an installed app that looks like it belongs on the device and one that looks like a browser tab wearing a costume.
background_color
background_color is shown briefly as a solid fill during the PWA's launch, in the moment between tapping the icon and the app's actual content painting. It's not a persistent background — think of it as the color of the blank screen during startup, there specifically to avoid a jarring flash of white or an unstyled void while the real page loads.
display: "standalone"
This field controls how much browser UI shows once the app is installed and launched. "standalone" is what makes an installed PWA feel like a genuine app: no address bar, no browser tab strip, just your content in its own window. "browser" mode, by contrast, opens the installed app in a regular browser tab with all the normal chrome visible — which defeats most of the point of installing it. Other values ("fullscreen", "minimal-ui") exist for more specific cases, but "standalone" is the right default for most sites.
Why this file gates the install prompt, not just the icon
This is the part that surprises people: Chrome and Android don't treat the manifest as pure decoration. A valid manifest with correctly sized icons is one of the actual requirements for the browser to offer an "install app" or "add to home screen" prompt at all. Miss a required icon size, point icons at a file that 404s, or leave out name and short_name, and the prompt can simply fail to appear — with no error message telling you why, because from the browser's perspective your site just didn't qualify.
That makes debugging a missing install prompt mostly a manifest-validation problem. If icons are declared elsewhere but nothing's wired up correctly in site.webmanifest, our troubleshooting guide for favicons not showing up covers the broader set of causes, several of which apply to manifest icons specifically — wrong paths, wrong MIME types, and stale caches all show up here too.
Getting the file right without hand-writing it
Every field above needs to line up exactly — right sizes, right paths, right MIME types, a maskable variant with correct padding — for the file to actually do its job instead of silently failing to qualify. The generator produces a complete site.webmanifest alongside the matching icon files from a single source image, so the sizes and paths are correct by construction rather than assembled by hand and hoped for.
✦ Try the Generator
Drop in artwork, type a word, or pick an emoji. Watch it land in a real browser tab, then export every size a modern site needs.
Open Generator