What a web app manifest does

A web app manifest is a JSON file that instructs the browser how your Progressive Web App (PWA) should behave once installed on a user's desktop or mobile device. At a minimum, a typical manifest includes the app's name, the icons to use, and the URL that opens when the app launches.

Creating the manifest file

The manifest file can be named anything, though it is commonly called manifest.json and served from your site's root directory. While the specification suggests using the .webmanifest extension, many developers prefer plain JSON files for readability.

A typical manifest resembles the following:

{
  "short_name": "Weather",
  "name": "Weather: Do I need an umbrella?",
  "icons": [
    {
      "src": "/images/icons-vector.svg",
      "type": "image/svg+xml",
      "sizes": "512x512"
    },
    {
      "src": "/images/icons-192.png",
      "type": "image/png",
      "sizes": "192x192"
    },
    {
      "src": "/images/icons-512.png",
      "type": "image/png",
      "sizes": "512x512"
    }
  ],
  "id": "/?source=pwa",
  "start_url": "/?source=pwa",
  "background_color": "#3367D6",
  "display": "standalone",
  "scope": "/",
  "theme_color": "#3367D6",
  "shortcuts": [
    {
      "name": "How's the weather today?",
      "short_name": "Today",
      "description": "View weather information for today",
      "url": "/today?source=pwa",
      "icons": [{ "src": "/images/today.png", "sizes": "192x192" }]
    },
    {
      "name": "How's the weather tomorrow?",
      "short_name": "Tomorrow",
      "description": "View weather information for tomorrow",
      "url": "/tomorrow?source=pwa",
      "icons": [{ "src": "/images/tomorrow.png", "sizes": "192x192" }]
    }
  ],
  "description": "Weather forecast information",
  "screenshots": [
    {
      "src": "/images/screenshot1.png",
      "type": "image/png",
      "sizes": "540x720",
      "form_factor": "narrow"
    },
    {
      "src": "/images/screenshot2.jpg",
      "type": "image/jpg",
      "sizes": "720x540",
      "form_factor": "wide"
    }
  ]
}

Core manifest properties

short_name and name

You must provide at least one of these two properties. When both are present, name is used at installation time, while short_name appears on the user's home screen, launcher, or other space-constrained locations.

icons

The icons property defines a set of images the browser can use for the home screen, app launcher, task switcher, splash screen, and elsewhere. Each object in the array must include src, sizes, and type. To enable maskable (adaptive) icons on Android, add "purpose": "any maskable".

For Chromium browsers, you must provide at least a 192x192 pixel icon and a 512x512 pixel icon. If you supply only those two sizes, Chrome will automatically scale them to fit the device. For pixel-perfect results, provide icons in increments of 48dp.

id

The id property explicitly defines the application identifier, removing the dependency on the start_url or the manifest's location. This makes it possible to change those values in the future without breaking the app's identity.

start_url

This required property tells the browser where the app should begin when launched, preventing it from starting on whatever page the user happened to be viewing during installation. The start_url should take users directly into your app's core experience, not to a landing page.

background_color

This property colors the splash screen that appears on mobile during the app's initial launch.

display

The display property controls which browser UI elements appear when the app launches. Options range from hiding the address bar to fullscreen mode for games:

Property Behavior
fullscreen Opens the web app without any browser UI and takes up all of the available display area.
standalone Opens the web app to look and feel like a standalone app. The app runs in its own window, separate from the browser, and hides standard browser UI elements such as the address bar.
An example of a PWA window with standalone display.
The standalone UI.
minimal-ui This mode is similar to standalone, but provides the user with a minimal set of UI elements for controlling navigation, such as the back and reload buttons.
An example of a PWA window with minimal-ui display.
The minimal UI.
browser A standard browser experience.

display_override

Browsers are required to support a specific fallback chain for display modes ("fullscreen" → "standalone" → "minimal-ui" → "browser"), but they are not required to support every mode. This can cause issues: for instance, a developer cannot request "minimal-ui" without falling back to "browser" if the former is unsupported. It also prevents new display modes from being added in a backwards-compatible way.

The display_override property lets you define your own fallback sequence. The browser evaluates it before the display property, applying the first supported mode in your list. If none are supported, it falls back to display; if that field is missing entirely, display_override is ignored.

For example:

{
  "display_override": ["window-control-overlay", "minimal-ui"],
  "display": "standalone",
}

With this configuration, the browser first attempts "window-control-overlay", then "minimal-ui", then "standalone" from the display property. If none of these are available, it uses the standard fallback chain.

scope

The scope property defines the set of URLs the browser considers part of your app. It controls the URL structure containing all entry and exit points, and helps the browser determine when the user has navigated away.

Keep these points in mind:

  • Without a scope, the implied scope is the start URL with its filename, query, and fragment removed.
  • The scope can be a relative path (../) or any higher-level path (/) that increases navigation coverage.
  • The start_url must fall within the scope.
  • A start_url beginning with / always resolves to the origin's root.

theme_color

This property sets the toolbar color and may be reflected in task switcher previews. It should match the meta theme color in your document head.

An example of a PWA window with custom theme_color.
An example of a PWA window with custom theme_color.

theme_color with media queries

Using the media attribute on the theme color meta element, you can define different colors for light and dark modes. However, the manifest itself cannot express these preferences. See the w3c/manifest#975 GitHub issue for more context.

<meta name="theme-color" media="(prefers-color-scheme: light)" content="white">
<meta name="theme-color" media="(prefers-color-scheme: dark)"  content="black">

shortcuts

The shortcuts property is an array of app shortcut objects that offer quick access to key tasks. Each member requires at least a name and a url.

description

The description property explains your app's purpose. In Chrome, descriptions were truncated at 300 characters across all platforms, with an ellipsis for longer text. On Android, the description was also limited to seven lines.

screenshots

This property is an array of image objects showing your app in typical usage scenarios. Each must include src, sizes, and type. The optional form_factor can be "wide" or "narrow" to indicate intended screen types.

Chrome enforces these criteria for screenshots:

  • Width and height must be between 320 px and 3840 px.
  • The maximum dimension cannot exceed 2.3 times the minimum dimension.
  • Screenshots matching a given form factor must share the same aspect ratio.
  • From Chrome 109, only screenshots with form_factor: "wide" appear on desktop; such screenshots are ignored on Android.

Chrome on desktop shows at least one and up to eight qualifying screenshots; the rest are ignored. Chrome on Android displays at least one and up to five.

Screenshots of richer installation UI on desktop and mobile.
Richer installation UI on desktop and mobile.

Linking the manifest to your pages

After creating the manifest, add a <link> tag to every page of your PWA:

<link rel="manifest" href="https://web.dev/manifest.json">

Verifying your manifest

In Chrome DevTools, the Manifest pane within the Application panel provides a human-readable view of many manifest properties and confirms that all images load correctly.

The application panel in Chrome Devtools with the manifest tab selected.
Test your manifest in DevTools.

Mobile splash screens

During the initial launch on mobile, the browser displays a splash screen until the first paint occurs. Chrome automatically builds this splash screen from the name, background_color, and icons in your manifest. For a seamless transition, set background_color to match your page's background.

Chrome selects the icon that best matches the device resolution for the splash screen. The recommended 192px and 512px icons suffice for most devices, but additional sizes can yield better results.