maskable icons, sometimes referred to as adaptive icons on Android, you'll also need to add
"purpose": "any maskable" to the
For Chrome, you must provide at least a 192x192 pixel icon, and a 512x512 pixel icon. If only those two icon sizes are provided, Chrome will automatically scale the icons to fit the device. If you'd prefer to scale your own icons, and adjust them for pixel-perfection, provide icons in increments of 48dp.
start_url is required and tells the browser where your application should start when it is launched, and prevents the app from starting on whatever page the user was on when they added your app to their home screen.
start_url should direct the user straight into your app, rather than a product landing page. Think about what the user will want to do once they open your app, and place them there.
background_color property is used on the splash screen when the application is first launched on mobile.
You can customize what browser UI is shown when your app is launched. For example, you can hide the address bar and browser chrome. Games can even be made to launch full screen.
|Opens the web application without any browser UI and takes up the entirety of the available display area.|
|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 like the URL bar.|
|This mode is similar to |
|A standard browser experience.|
Web apps can choose how they are displayed by setting a
display mode in their manifest as explained above. Browsers are not required to support all display modes, but they are required to support the spec-defined fallback chain (
"browser"). If they don't support a given mode, they fall back to the next display mode in the chain. This inflexible behavior can be problematic in rare cases, for example, a developer cannot request
"minimal-ui" without being forced back into the
"browser" display mode when
"minimal-ui" is not supported. Another problem is that the current behavior makes it impossible to introduce new display modes in a backward compatible way, since explorations like tabbed application mode don't have a natural place in the fallback chain.
These problems are solved by the
display_override property, which the browser considers before the
display property. Its value is a sequence of strings that are considered in the listed order, and the first supported display mode is applied. If none are supported, the browser falls back to evaluating the
In the example below, the display mode fallback chain would be as follows. (The details of
"window-control-overlay" are out-of-scope for this article.)
"window-control-overlay"(First, look at
display_overrideis exhausted, evaluate
"minimal-ui"(Finally, use the
"display_override": ["window-control-overlay", "minimal-ui"],
The browser will not consider
display is also present.
scope defines the set of URLs that the browser considers to be within your app, and is used to decide when the user has left the app. The
scope controls the URL structure that encompasses all the entry and exit points in your web app. Your
start_url must reside within the
Caution: If the user clicks a link in your app that navigates outside of the
scope, the link will open and render within the existing PWA window. If you want the link to open in a browser tab, you must add
target="_blank" to the
<a> tag. On Android, links with
target="_blank" will open in a Chrome Custom Tab.
A few other notes on
scopein your manifest, then the default implied
scopeis the directory that your web app manifest is served from.
scopeattribute can be a relative path (
../), or any higher level path (
/) which would allow for an increase in coverage of navigations in your web app.
start_urlmust be in the scope.
start_urlis relative to the path defined in the
/will always be the root of the origin.
theme_color sets the color of the tool bar, and may be reflected in the app's preview in task switchers. The
theme_color should match the
meta theme color specified in your document head.
shortcuts property is an array of app shortcut objects whose goal is to provide quick access to key tasks within your app. Each member is a dictionary that contains at least a
name and a
description property describes the purpose of your app.
screenshots property is an array of image objects, representing your app in common usage scenarios. Each object must include the
sizes property, and the
type of image.
In Chrome, the image must respond to certain criteria:
screenshots properties are currently used only in Chrome for Android when a user wants to install your app. The experimental flag
chrome://flags/#mobile-pwa-install-use-bottom-sheet flag must be enabled in Chrome 90.
After creating the manifest, add a
<link> tag to all the pages of your Progressive Web App. For example:
<link rel="manifest" href="/manifest.json">
The request for the manifest is made without credentials (even if it's on the same domain), thus if the manifest requires credentials, you must include
crossorigin="use-credentials" in the manifest tag.
To verify your manifest is setup correctly, use the Manifest pane in the Application panel of Chrome DevTools.
This pane provides a human-readable version of many of your manifest's properties, and makes it easy to verify that all of the images are loading properly.
When your app first launches on mobile, it can take a moment for the browser to spin up, and the initial content to begin rendering. Instead of showing a white screen that may look to the user like the app is stalled, the browser will show a splash screen until the first paint.
Chrome automatically creates the splash screen from the manifest properties, specifically:
background_color should be the same color as the load page, to provide a smooth transition from the splash screen to your app.
Chrome will choose the icon that closely matches the device resolution for the device. Providing 192px and 512px icons is sufficient for most cases, but you can provide additional icons for pixel perfection.
There are several additional properties that can be added to the web app manifest. Refer to the MDN Web App Manifest documentation for more information. You can learn more about
display_override in the explainer.