Add a web app manifest

A web app manifest is a JSON file that tells the browser how your Progressive Web App (PWA) should behave when installed on the user's desktop or mobile device. At minimum, a typical manifest file includes:

• The app's name
• The icons the app should use
• The URL that should be opened when the app launches

Create the manifest file

The manifest file can have any name, but it's commonly namedmanifest.jsonand served from the root (your website's top-level directory). The specification suggests the extension should be.webmanifest,but you might want to use JSON files to make your manifests clearer to read.

A typical manifest looks like this:

{
"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"
}
]
}

Key manifest properties

short_nameandname

You must provide at least one ofshort_nameornamein your manifest. If you provide both,nameis used when the app is installed, andshort_nameis used on the user's home screen, launcher, or other places where space is limited.

icons

When a user installs your PWA, you can define a set of icons for the browser to use on the home screen, app launcher, task switcher, splash screen, and in other places.

Theiconsproperty is an array of image objects. Each object must include thesrc,asizesproperty, and thetypeof image. To use maskable icons,sometimes referred to as adaptive icons on Android, add"purpose": "any maskable"to theiconproperty.

For Chromium, you must provide at least a 192x192 pixel icon and a 512x512 pixel icon. If only those two icon sizes are provided, Chrome automatically scales 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.

id

Theidproperty lets you explicitly define the identifier used for your application. Adding theidproperty to the manifest removes the dependency on thestart_urlor the location of the manifest, and makes it possible to update them in the future. For more information, see Uniquely identifying PWAs with the web app manifest ID property.

start_url

Thestart_urlis a required property. It tells the browser where your app should start when it launches, and prevents the app from starting on whatever page the user was on when they added your app to their home screen.

Yourstart_urlshould direct the user straight into your app, not a product landing page. Think about what the user will want to do immediately after they open your app, and place them there.

background_color

Thebackground_colorproperty is used on the splash screen when the application launches on mobile for the first time.

display

You can customize what browser UI is shown when your app is launched. For example, you can hide the address bar and browser user interface elements. Games can even be made to launch in full screen. Thedisplayproperty takes one of the following values:

display_override

To choose how your web app is displayed, set adisplaymode in its manifest as explained earlier.Browsers aren't required to support all display modes, but theyarerequired to support the spec-defined fallback chain ("fullscreen"→"standalone"→"minimal-ui"→"browser"). If they don't support a given mode, they fall back to the next display mode in the chain. In rare cases, these fallbacks can cause problems. For example, a developer can't request"minimal-ui"without being forced back into the"browser"display mode when"minimal-ui"is not supported. The current behavior also makes it impossible to introduce new display modes in a backwards-compatible way, because they don't have a place in the fallback chain.

You can set your own fallback sequence using thedisplay_overrideproperty, which the browser considersbeforethedisplayproperty. 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 thedisplayfield. If there's nodisplayfield, the browser ignoresdisplay_override.

The following is an example of how to usedisplay_override.The details of "window-control-overlay"are out of scope for this page.

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

When loading this app, the browser tries to use"window-control-overlay" first. If that's unavailable, it falls back to"minimal-ui",and then to "standalone"from thedisplayproperty. If none of these are available, the browser then returns to the standard fallback chain.

scope

Thescopeof your app is the set of URLs that the browser considers part of your app.scopecontrols the URL structure that includes all entry and exit points to the app, and the browser uses it to determine when the user has left the app.

A few other notes onscope:

• If you don't include ascopein your manifest, then the default implied scopeis the start URL, but with its filename, query, and fragment removed.
• Thescopeattribute can be a relative path (../), or any higher level path (/) that would allow for an increase in coverage of navigations in your web app.
• Thestart_urlmust be in the scope.
• Thestart_urlis relative to the path defined in thescopeattribute.
• Astart_urlstarting with/will always be the root of the origin.

theme_color

Thetheme_colorsets the color of the tool bar, and can be reflected in the app's preview in task switchers. Thetheme_colorshould match the metatheme color specified in your document head.

theme_colorin media queries

You can adjusttheme_colorin a media query using themediaattribute of the metatheme color element. For example, you can define one color for light mode and another one for dark mode in this way. However, you can't define these preferences in your manifest. For more information, see the w3c/manifest#975 GitHub issue.

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

shortcuts

Theshortcutsproperty is an array ofapp shortcut objects that provide quick access to key tasks within your app. Each member is a dictionary that contains at least anameand aurl.

description

Thedescriptionproperty describes the purpose of your app.

In Chrome, the maximum description length is 300 characters on all platforms. If the description is longer than that, the browser truncates it with an ellipsis character. On Android, the description must also use a maximum of seven lines of text.

screenshots

Thescreenshotsproperty is an array of image objects representing your app in common usage scenarios. Each object must include thesrc,asizes property, and thetypeof image. Theform_factorproperty is optional. You can set it either to"wide"for screenshots applicable to wide screens only or"narrow"for only narrow screenshots.

In Chrome, the image must meet the following criteria:

• Width and height must be at least 320 px and at most 3840 px.
• The maximum dimension can't be more than 2.3 times the length of the minimum dimension.
• All screenshots matching the appropriate form factor must have the same aspect ratio.
  • From Chrome 109, only screenshots with theform_factorset to"wide" are displayed on desktop.
• From Chrome 109, screenshots with theform_factorset to"wide"are ignored on Android. Screenshots withoutform_factorare still displayed for backwards compatibility.

Chrome on desktop displays at least one and at most eight screenshots that meet these criteria. The rest are ignored.

Chrome on Android displays at least one and at most five screenshots that meet these criteria. The rest are ignored.

Add the web app manifest to your pages

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" >

Test your manifest

To verify your manifest is set up correctly, use theManifestpane in the Applicationpanel of Chrome DevTools.

This pane provides a human-readable version of many of your manifest's properties, and lets you verify that all of the images are loading properly.

Splash screens on mobile

When your app first launches on mobile, it can take a moment for the browser to start and the initial content to begin rendering. Instead of showing a white screen that might make the user think the app isn't working, the browser shows a splash screen until the first paint.

Chrome automatically creates the splash screen from thename, background_color,andiconsspecified in your manifest. To create a smooth transition from the splash screen to the app, make youbackground_colorthe same color as the load page.

Chrome chooses the icon that most closely matches the device resolution for the splash screens. Providing 192px and 512px icons is sufficient for most cases, but you can provide additional icons for a better match.

Further reading

To learn about other properties you can add to your web app manifest, refer to theMDN Web App Manifest documentation.