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 named
manifest.json
and
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.
You must provide at least one of
short_name
or
name
in your manifest. If
you provide both,
name
is used when the app is installed, and
short_name
is
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.
The
icons
property is an array of image objects. Each object must
include the
src
, a
sizes
property, and the
type
of image. To use
maskable icons
, sometimes referred to as adaptive
icons on Android, add
"purpose": "any maskable"
to the
icon
property.
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.
The
id
property lets you explicitly define the identifier used for your
application. Adding the
id
property to the manifest removes the dependency on
the
start_url
or 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
The
start_url
is 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.
Your
start_url
should 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
The
background_color
property 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. The
display
property takes one of
the following values:
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.
The standalone 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.
The minimal UI.
display_override
To choose how your web app is displayed, set a
display
mode in its manifest as
explained earlier
. Browsers aren't required to support all display
modes, but they
are
required 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 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
display
field. If there's no
display
field, the browser
ignores
display_override
.
The following is an example of how to use
display_override
. The details of
"window-control-overlay"
are out of scope
for this page.
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 the
display
property. If none of these are available, the
browser then returns to the standard fallback chain.
scope
The
scope
of your app is the set of URLs that the browser considers part of
your app.
scope
controls 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 on
scope
:
If you don't include a
scope
in your manifest, then the default implied
scope
is the start URL, but with its filename, query, and fragment removed.
The
scope
attribute can be a relative path (
../
), or any higher level
path (
/
) that would allow for an increase in coverage of navigations
in your web app.
The
start_url
must be in the scope.
The
start_url
is relative to the path defined in the
scope
attribute.
A
start_url
starting with
/
will always be the root of the origin.
theme_color
The
theme_color
sets the color of the tool bar, and can be reflected in
the app's preview in task switchers. The
theme_color
should match the
meta
theme color specified in your document head.
You can adjust
theme_color
in a media query using the
media
attribute of the
meta
theme 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
.
The shortcuts property is an array of app shortcut
objects that provide quick access to key tasks within your app. Each member
is a dictionary that contains at least a name and a url.
description
The description property 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
The screenshots property is an array of image objects representing your app
in common usage scenarios. Each object must include the src, a sizes
property, and the type of image. The form_factor property 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 the form_factor set to "wide"
are displayed on desktop.
From Chrome 109, screenshots with the form_factor set to "wide" are
ignored on Android. Screenshots without form_factor are 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 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 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 the name,
background_color, and icons specified in your manifest. To create a smooth
transition from the splash screen to the app, make you background_color the
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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-09-18 UTC."],[],[],null,[]]
