Web app manifest: every field explained, with examples

A web app manifest is a small JSON file that tells a browser how your site should behave once it is installed: its name, icons, colors, start page and window style. You link it from your pages with one <link rel="manifest"> tag. Chrome needs a valid manifest, with specific fields, before it will offer to install your site.

This page starts with a complete example you can copy, then explains each field: what it does, which value to use, and the mistake people usually make. If your site won’t install, jump to common mistakes.

A complete example

This is a full manifest for a made-up business called Bloom Studio. Swap in your own names, colors and file paths.

{
  "id": "/",
  "name": "Bloom Studio",
  "short_name": "Bloom",
  "description": "Book plant care visits and get reminders.",
  "start_url": "/",
  "scope": "/",
  "display": "standalone",
  "theme_color": "#5a0fc8",
  "background_color": "#ffffff",
  "icons": [
    {
      "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/maskable-192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "maskable"
    },
    {
      "src": "/icons/maskable-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ],
  "screenshots": [
    {
      "src": "/screenshots/phone.png",
      "sizes": "1080x1920",
      "type": "image/png",
      "form_factor": "narrow",
      "label": "Upcoming visits on a phone"
    },
    {
      "src": "/screenshots/desktop.png",
      "sizes": "1920x1080",
      "type": "image/png",
      "form_factor": "wide",
      "label": "The visit calendar on a laptop"
    }
  ]
}

Save it as manifest.webmanifest in your site’s public folder. Then add these tags to the head of your page:

<link rel="manifest" href="/manifest.webmanifest" />
<meta name="theme-color" content="#5a0fc8" />
<link rel="apple-touch-icon" href="/apple-touch-icon.png" />
<meta name="apple-mobile-web-app-title" content="Bloom" />

The first two tags serve Chrome and other browsers. The last two serve iPhone. If you’d rather not write this by hand, the manifest generator builds both from a form.

Which fields matter

The table shows what each field does and whether Chrome and iPhone use it. “Chrome” means desktop and Android. “iPhone” means Safari on iOS, with the first iOS version that supports the field. A dash means there’s no clear browser data for that cell.

Field	What it does	Needed to install in Chrome?	Used by Safari on iPhone?
name	Full app name	Yes, name or short_name	Yes, iOS 11.3+
short_name	Name under the icon	Yes, name or short_name	Yes, iOS 11.3+
start_url	Page the app opens on	Yes	Yes, iOS 11.3+
id	Stable identity of the app	No	Yes, iOS 16.4+
scope	URLs that belong to the app	No	Yes, iOS 11.3+
display	Window style	Yes, or display_override	standalone and browser, iOS 11.3+
display_override	Display modes to try first	Counts in place of display	No
icons	App icons	Yes, 192px and 512px	Yes, iOS 15.4+, with limits
theme_color	Color of the app’s window	No	Yes, iOS 15+
background_color	Color while loading	No	No Safari support listed
description	Text in Chrome’s install dialog	No	No
screenshots	Images for install dialog and stores	No	—
shortcuts	Quick actions on the icon	No	No
orientation	Preferred screen orientation	No	No Safari support listed
prefer_related_applications	Prefers your native app	Must be absent or false	—
related_applications	Lists your native apps	No	—
share_target	Appears in the share sheet	No	No

Chrome also shows its install prompt only after some engagement: one click or tap, and 30 seconds on the page.

Three more fields exist: lang, dir and categories. They are optional, and this guide doesn’t cover them.

The fields, one by one

name and short_name

name is the full name. Chrome shows it in install prompts and app lists. short_name appears under the icon on the Home Screen, where phones show about 12 characters.

Chrome needs one of the two, but set both. Use your brand name for name and a trimmed version for short_name.

The common mistake is a short_name that is too long. It gets cut off under the icon.

start_url

start_url is the page your app opens on when someone taps its icon. Use "/" or "./", which are the safe choices. Chrome requires it to install, and some other browsers do too.

Relative values resolve against the manifest’s URL. The value must be on the same origin as the page that links the manifest. If it is missing or invalid, the browser uses the URL of the linking page.

MDN says a launch parameter such as ?launcher=homescreen is fine for analytics, but it can add to fingerprinting (identifying a visitor by small details). Never put a user ID in start_url.

id

id is the unique identity of your app. Set "id": "/", or another stable path, from the start.

Relative values resolve against the origin of start_url. The id must be same-origin with start_url, and any fragment is dropped. If you leave it out, the browser uses start_url as the id.

This matters because a manifest whose id matches an installed app replaces that app’s manifest. A different id means a different app. If you change start_url later and never set an id, browsers can treat the result as a new app. Chrome supports id from version 96.

scope

scope says which URLs belong to the app. Use "/" for a whole site, or a path such as /app/ for part of it.

Relative values resolve against the manifest’s URL. If scope is missing or invalid, it becomes the start_url without its file name, query and fragment. It is invalid if start_url isn’t inside it.

Matching is a simple prefix match, so end the path with a slash. Scope doesn’t block navigation. Pages outside it still open, but the browser shows extra UI such as the URL bar.

display

display sets the window style. The values are:

• fullscreen: all of the screen, with browser UI hidden.
• standalone: looks like a native app, with its own window and launcher icon.
• minimal-ui: like standalone, with a few navigation controls.
• browser: a normal browser tab. This is the default.

Use standalone for most apps. If a browser doesn’t support a mode, it falls back in this order: fullscreen, standalone, minimal-ui, browser.

Chrome accepts fullscreen, standalone, minimal-ui or window-controls-overlay for install. Safari supports standalone and browser. MDN lists no Safari support for fullscreen or minimal-ui.

iPhone delivers web push only to Home Screen web apps whose display is standalone or fullscreen. If you want push on iPhone, browser is the wrong value.

display_override

display_override is an ordered list of display modes to try before display. Chrome supports it from version 89. Safari doesn’t.

Its values include window-controls-overlay, where the app draws into the title bar area on desktop (Chrome 105+), and tabbed (Chrome 126+). Always keep a normal display value as the fallback.

"display_override": ["window-controls-overlay"],
"display": "standalone"

icons

icons is a list. Each icon has:

• src: the file path, resolved against the manifest’s URL.
• sizes: for example "192x192". You can list several sizes separated by spaces, or use "any" for SVG.
• type: for example image/png.
• purpose: what the icon is for.

There are three purposes. any is the default. maskable means the icon is designed for the safe zone, so the system can crop it to a circle, squircle or other shape. monochrome means only the alpha channel is used, and the system fills it with one color.

Chrome needs a 192px and a 512px icon. Provide both as any, and add maskable versions as in the example.

The maskable safe zone is a circle at the center of the icon with a radius of 40% of the icon size. Anything outside it may be cropped.

On iPhone, Safari uses manifest icons only when there is no apple-touch-icon, and only icons whose purpose is any or not set. The icon generator makes all the sizes from one logo.

theme_color and background_color

theme_color is the default theme color for the app’s windows. The browser may use it for its own UI, such as the title bar. Also set <meta name="theme-color"> in the page, as in the head tags above.

background_color is a placeholder color shown before your stylesheet is available. It only improves the experience while the app loads. Chrome uses it for the splash screen color on Android.

Chrome supports both from version 46. Safari on the Mac supports theme_color from version 17, and iPhone from iOS 15. MDN lists no Safari support for background_color.

description

description is a sentence about the app. Chrome’s richer install dialog shows it. It is recommended, not required. Chrome supports it from version 88, and Safari doesn’t.

screenshots

screenshots are optional. MDN says they are mainly used by app stores, and the app works without them.

Each screenshot has a required src, plus sizes, type, label, form_factor and platform. Set label on every screenshot, since it is the accessible name. Use form_factor narrow for phones and wide for desktops. If you leave it out, the screenshot applies to all.

Chrome shows its richer install dialog when the manifest has at least one screenshot for that form factor. That started on Android with Chrome 94 and on desktop with Chrome 108, according to a 2021 Chrome post. Without screenshots, Chrome shows its normal prompt.

shortcuts

shortcuts adds quick actions to the app icon, reached by long-press or right-click. Chrome supports it from version 96 (Android 84+). Safari supports it from 17.4 on macOS, but not on iPhone. Skip it unless your app has a clear first action.

orientation

orientation sets a preferred screen orientation. Chrome supports it from version 39. MDN lists no Safari support. Leave it out unless your app really only works one way.

related_applications and prefer_related_applications

related_applications lists your native apps. prefer_related_applications: true tells Chrome on Android to offer your native app instead of installing the web app.

For the web app to install, prefer_related_applications must be absent or false. Don’t set it to true unless you want that behavior.

share_target

share_target lets the installed app appear in the system share sheet. Chrome supports it from version 89 (Android 76+). Safari doesn’t. It’s optional, and most apps don’t need it.

Where to put the manifest and how to link it

1. Create the file in your public folder, for example manifest.webmanifest.
2. Add <link rel="manifest" href="/manifest.webmanifest"> to the head of your pages.
3. Serve the file as application/manifest+json.
4. Open the file’s URL in your browser and check that it loads as JSON.

The registered file extension is .webmanifest. Browsers read whatever file the link tag points to, so manifest.json works too. Pick one name and use it everywhere.

Relative URLs in the manifest, such as icon paths, resolve against the manifest’s URL, not the page’s. Starting every path with / keeps this simple.

The manifest can be hosted on another origin. If you do that, start_url must still be on the same origin as the page that links it.

What iPhone uses (and what it ignores)

Safari on iPhone reads many manifest fields. The table above shows the iOS version each one needs. It doesn’t support display_override, description, shortcuts or share_target.

The Home Screen icon comes from <link rel="apple-touch-icon"> if you have one. Use a 180×180 PNG. Set apple-mobile-web-app-title to the same short name as your manifest’s short_name.

iOS launch screens use <link rel="apple-touch-startup-image"> tags, one per screen size. The icon generator makes those too, with the tags.

iOS 26 and iPadOS 26 changed one thing. The WebKit blog says: “By default, every website added to the Home Screen opens as a web app.” A manifest is no longer required for that. Safari still uses a manifest’s icons and settings when there is one, so it’s worth having.

Common mistakes

• Missing 192px or 512px icon. Chrome needs both. Add them with purpose set to any.
• Icon files that 404 or have the wrong size. Open each src URL in a browser. Make sure sizes matches the real pixel size.
• Maskable-only icons. Safari on iPhone ignores icons whose only purpose is maskable. Always include any icons too.
• Logo outside the maskable safe zone. Keep the logo inside the central circle with a radius of 40% of the icon size, or it may be cropped.
• display: browser. This is a normal tab, and it isn’t one of the display modes Chrome accepts for install. Use standalone.
• start_url outside scope. The scope becomes invalid. Make sure start_url sits inside scope.
• Changing start_url later without an id. Browsers can treat it as a second installed app. Set "id": "/" from day one.
• prefer_related_applications: true. This blocks install in Chrome. Remove it or set it to false.
• A short_name that is too long. Phones show about 12 characters under the icon. Shorten it.
• Tracking IDs in start_url. A launch parameter for analytics is fine. A user ID is not.

Check your manifest

The quickest test is to run the free PWA checker on your live site. We built it to test a live URL for install, iPhone, push, offline and app store readiness.

You can also open Chrome DevTools, then go to Application, then Manifest, to see how Chrome reads your file.

To make a manifest from scratch, use the manifest generator. It outputs a valid manifest.webmanifest and the HTML tags, and warns about mistakes that stop install or iPhone push. For the icons, use the icon generator. Both are free, run in your browser and store nothing.

The free route is enough if you’re comfortable editing your site’s head and public folder. If you’d rather hand it off, Setup ($149, one-time) has us add the manifest, icons, iOS launch screens, a service worker and push, tested on real phones.