1. name
What it is: the full official name of the application.
Why it matters: this is the name the browser and operating system try to use wherever there is enough space: in the install dialog, in the app list, sometimes on the splash screen, and in system app switchers and menus.
Practical usage: if you have a short name for everyday use but a longer, more descriptive official name, the branded full name should live here.
Value: string. There is no strict formal length limit, but very long names will be truncated in UI.
Chrome / Chromium: this field is actually used in the install UI, app lists, and other PWA scenarios.
Safari: may use this name for a web app added to the home screen, but behavior depends on the specific Apple platform and UI.
Example:
{
"name": "ShkurkoDev Web App Manifest Guide"
}
2. short_name
What it is: a shorter version of the application name.
Why it matters: used where the full name does not fit - for example, under the icon on the home screen or in compact UI elements.
Practical usage: it almost always makes sense to set this alongside name, especially if the brand name is long.
Value: string. In practice it is better to keep it short so it does not get truncated.
Chrome / Chromium: actively used when name is too long.
Safari: may use the short name as the caption under the home screen icon.
Example:
{
"name": "ShkurkoDev Web App Manifest Guide",
"short_name": "Manifest"
}
3. lang
What it is: the language of the strings inside the manifest.
Why it matters: in theory this should tell the browser which language text values like name and description are written in.
Practical usage: as of now it has almost no real impact, because browsers do not implement it.
Possible values: BCP 47 language tags, such as ru, en, en-US, pt-BR.
Chrome / Chromium: the spec describes this field, but there is no real implementation.
Safari: no practical support either.
Example:
{
"lang": "ru"
}
4. dir
What it is: text direction within the manifest.
Why it matters: intended primarily for right‑to‑left languages such as Arabic or Hebrew.
Possible values: ltr, rtl, auto.
Practical usage: almost none, because browsers do not implement it as a working manifest feature.
Chrome / Chromium: not implemented.
Safari: not implemented.
Example:
{
"dir": "rtl"
}
5. description
What it is: a text description of what the app does.
Why it matters: helps users understand the purpose of the PWA, especially if the browser shows a richer install UI or an app‑store‑like install experience.
Practical usage: mainly useful in the Chromium ecosystem. For content projects, services, note apps, catalogs, editors and internal tools, it is a good place for a short, clear description of the value your app provides.
Value: string.
Chrome / Chromium: may be used in richer install UI.
Safari: usually does not use this field in any visible way.
Example:
{
"description": "A detailed guide to the Web App Manifest with examples, explanations, and a comparison of browser support."
}
6. icons
What it is: a list of app icons of different sizes, formats and purposes.
Why it matters: this is one of the most important fields. The browser and OS use it to choose which icon to show in the install UI, on the home screen, in app lists and sometimes when generating the splash screen.
Practical usage: the minimum is usually PNG 192×192 and 512×512. If you want a nice Android look, it is worth adding a maskable icon.
Object structure: typically uses src, sizes, type, purpose.
Possible purpose values: any, maskable, monochrome. They can be combined with spaces if that fits your icon pipeline.
Chrome / Chromium: this is the primary source of icons for PWAs.
Safari: the icons section alone is often not enough. For iOS you usually also add <link rel="apple-touch-icon"> in HTML.
Simple example:
{
"icons": [
{
"src": "/icons/icon-192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "/icons/icon-512.png",
"sizes": "512x512",
"type": "image/png"
}
]
}
Maskable example:
{
"icons": [
{
"src": "/icons/icon-192.png",
"sizes": "192x192",
"type": "image/png",
"purpose": "any"
},
{
"src": "/icons/icon-512-maskable.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "maskable"
}
]
}
7. screenshots
What it is: screenshots of the app UI.
Why it matters: does not affect how the PWA works, but helps show users what the app looks like when the browser supports a richer install UI.
Practical usage: useful in Chromium if you want the install flow to look richer and more informative.
Structure: array of objects. Usually uses src, sizes, type, form_factor.
Possible form_factor values: examples commonly use wide and narrow.
Chrome / Chromium: used in richer install UI.
Safari: typically ignores this field.
Basic example:
{
"screenshots": [
{
"src": "/screenshots/desktop-home.png",
"sizes": "1440x900",
"type": "image/png"
}
]
}
Example with different form factors:
{
"screenshots": [
{
"src": "/screenshots/mobile-home.png",
"sizes": "540x720",
"type": "image/png",
"form_factor": "narrow"
},
{
"src": "/screenshots/desktop-dashboard.png",
"sizes": "1440x900",
"type": "image/png",
"form_factor": "wide"
}
]
}
8. categories
What it is: a list of categories the app belongs to.
Why it matters: helps describe the type of app to ecosystems, catalogs and app‑store‑like UIs.
Practical usage: has almost no effect on how the PWA behaves; it is mostly metadata.
Value: array of strings, for example productivity, business, education.
Chrome / Chromium: may be used somewhere in the install / catalog infrastructure.
Safari: almost no practical impact.
Example:
{
"categories": ["education", "productivity", "developer tools"]
}
9. iarc_rating_id
What it is: a string identifier of the IARC age rating.
Why it matters: intended for integration with app‑publishing systems and storefront scenarios where age ratings are required.
Practical usage: almost never needed for a typical website or standard PWA.
Value: string containing the IARC code.
Chrome / Chromium: not implemented as a normal manifest browser feature.
Safari: not used.
Example:
{
"iarc_rating_id": "e7f4a2b1-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
10. start_url
What it is: the URL that should open when the installed app is launched.
Why it matters: this is the PWA entry point. It is where users land after launching the app from its icon.
Practical usage: can point to the homepage, a dashboard, onboarding, or a specific section. A query parameter is often appended to detect launches from the installed PWA.
Value: relative or absolute URL.
Chrome / Chromium: actively used.
Safari: respected when launching a web app, but actual UX depends on Add to Home Screen on the specific Apple platform.
Simple example:
{
"start_url": "/"
}
Section example:
{
"start_url": "/app/"
}
Example with a query parameter:
{
"start_url": "/app/?source=pwa"
}
11. scope
What it is: the URL area the browser treats as part of the application.
Why it matters: defines the app‑like boundary. Pages inside scope are treated as part of the PWA; when leaving scope, the browser may show regular browser UI such as the address bar.
Practical usage: if the app lives under /app/, scope is usually set to /app/ as well.
Important: start_url must be inside scope.
Chrome / Chromium: affects the app‑like interface and navigation behavior.
Safari: the concept is the same, but actual behavior can be less predictable.
Simple example:
{
"start_url": "/app/",
"scope": "/app/"
}
Whole‑site example:
{
"start_url": "/",
"scope": "/"
}
12. scope_extensions
What it is: an experimental mechanism for extending the app’s scope to other origins.
Why it matters: useful only in complex architectures where a single app should be perceived as one, even though some pages live on another domain or subdomain.
Practical usage: very rare. Most projects never need it.
Chrome / Chromium: experimental only.
Safari: not supported.
Generic example:
{
"scope_extensions": [
{
"type": "origin",
"origin": "https://cdn.example.com"
}
]
}
13. display
What it is: the preferred display mode of the app after installation.
Why it matters: determines how much browser UI the user sees.
Possible values: browser, minimal-ui, standalone, fullscreen.
What the values mean:
browser - normal browser tab; minimal-ui - minimal browser UI; standalone - looks like a standalone app without the usual tab; fullscreen - hides the UI as much as possible and uses the full screen.
Practical usage: standalone is the most common choice for PWAs.
Chrome / Chromium: behaves as expected with fallback logic when a mode is not supported.
Safari: support is incomplete and depends on the platform. A web app on the home screen may not behave the same way as a Chromium PWA.
Examples:
{
"display": "standalone"
}
{
"display": "fullscreen"
}
{
"display": "browser"
}
14. display_override
What it is: an ordered array of preferred display modes.
Why it matters: sometimes the basic fallback behavior of display is not enough, especially for advanced desktop PWA scenarios in Chromium.
Practical usage: useful when you want to request a newer mode first and fall back to standalone if it is not supported.
Value: array of strings.
Chrome / Chromium: partially supported, mainly in Chromium on desktop.
Safari: not supported.
Examples:
{
"display": "standalone",
"display_override": ["window-controls-overlay", "standalone"]
}
{
"display": "browser",
"display_override": ["tabbed", "standalone", "browser"]
}
15. orientation
What it is: the preferred screen orientation for the app.
Why it matters: helpful for games, media apps, kiosk interfaces, navigation, terminals and other scenarios where the UI is designed strictly for portrait or landscape.
Possible values: any, natural, portrait, landscape, portrait-primary, portrait-secondary, landscape-primary, landscape-secondary.
Chrome / Chromium: mostly honored in standalone / fullscreen modes.
Safari: especially on iOS, often ignores this field or handles it differently than Chromium.
Examples:
{
"orientation": "portrait"
}
{
"orientation": "landscape"
}
{
"orientation": "any"
}
16. theme_color
What it is: the default color for the app’s user interface.
Why it matters: can be applied to browser UI elements such as the toolbar, address bar, status area, and may be visible in the task switcher and similar surfaces.
Practical usage: usually set to your primary brand color.
Important: the HTML <meta name="theme-color"> tag can override this for a specific page. Browsers may also take into account user color schemes and CSS media queries.
Possible values: any valid CSS color: keyword, hex, rgb(), hsl().
Chrome / Chromium: this field is actively used.
Safari: effect is limited; in practice the HTML meta theme-color tag often matters more.
Examples:
{
"theme_color": "#0f172a"
}
{
"theme_color": "rgb(66 133 244)"
}
{
"theme_color": "white"
}
Example together with an HTML meta tag:
<meta name="theme-color" content="#111827">
17. background_color
What it is: the initial background color shown before the app’s styles finish loading.
Why it matters: helps avoid a harsh white flash on launch and makes the PWA startup visually cleaner.
Important: this field does not control the permanent background of your UI after the app has loaded. Once CSS is applied, it is in charge. background_color is a temporary initial color and a source for the splash background in some environments.
Practical usage: usually set to the same color as the main app background in CSS.
Possible values: any valid CSS color.
Chrome / Chromium: used for the initial background and to generate the splash screen in some environments.
Safari: often does not produce as noticeable an effect as in Chromium.
Example:
{
"background_color": "#f7f6f2"
}
Example together with CSS:
{
"background_color": "#f7f6f2"
}
body {
background-color: #f7f6f2;
}
18. shortcuts
What it is: quick actions for the installed application.
Why it matters: lets users open key sections of the PWA directly from the app icon’s context menu, without visiting the homepage first.
Practical usage: great for “New note”, “Open tasks”, “Favorites”, “Profile”, “Search”.
Structure: array of objects { name, short_name?, description?, url, icons? }.
Chrome / Chromium: works for installed PWAs in the Chromium ecosystem.
Safari: not supported.
Simple example:
{
"shortcuts": [
{
"name": "New note",
"url": "/notes/new"
}
]
}
Full example:
{
"shortcuts": [
{
"name": "New note",
"short_name": "New",
"description": "Quickly create a new note",
"url": "/notes/new",
"icons": [
{
"src": "/icons/new-note.png",
"sizes": "96x96",
"type": "image/png"
}
]
},
{
"name": "Favorites",
"url": "/favorites"
}
]
}
19. share_target
What it is: makes an installed PWA a target for the system share sheet.
Why it matters: users can send text, links, titles and sometimes files into your app.
Practical usage: especially useful for note apps, bookmark managers, editors, content managers, link‑sharing tools and import workflows.
Structure: object. action and params are required. method and enctype can also be used.
Possible method values: GET or POST.
Important: for files you must use POST, multipart/form-data and a params.files section.
Chrome / Chromium: works for installed PWAs.
Safari: not supported.
Simple example for title, text and URL:
{
"share_target": {
"action": "/share-target/",
"method": "GET",
"params": {
"title": "title",
"text": "text",
"url": "url"
}
}
}
Example using POST:
{
"share_target": {
"action": "/share-target/",
"method": "POST",
"enctype": "application/x-www-form-urlencoded",
"params": {
"title": "title",
"text": "text",
"url": "url"
}
}
}
Example with files:
{
"share_target": {
"action": "/share-target/",
"method": "POST",
"enctype": "multipart/form-data",
"params": {
"title": "title",
"text": "text",
"url": "url",
"files": [
{
"name": "images",
"accept": ["image/png", "image/jpeg"]
}
]
}
}
}
20. file_handlers
What it is: a list of file types that the installed PWA can open.
Why it matters: lets you associate files with the PWA at the OS level so users can open them directly in your app.
Practical usage: useful for text editors, CSV tools, graphics editors, SVG viewers, note apps and IDE‑like apps.
Structure: array of objects { action, accept }, where accept is a dictionary mapping MIME types to file extensions.
Important: the manifest alone is not enough. After launch, the app must actually handle the files in JavaScript, for example via window.launchQueue.
Chrome / Chromium: experimental.
Safari: not supported.
Example for plain text files:
{
"file_handlers": [
{
"action": "/open-file/",
"accept": {
"text/plain": [".txt"]
}
}
]
}
Example for multiple types:
{
"file_handlers": [
{
"action": "/open-file/",
"accept": {
"text/plain": [".txt", ".md"],
"text/csv": [".csv"],
"image/svg+xml": [".svg"]
}
}
]
}
JavaScript handling example:
if ('launchQueue' in window) {
launchQueue.setConsumer((launchParams) => {
for (const fileHandle of launchParams.files) {
console.log('Received file:', fileHandle);
}
});
}
21. protocol_handlers
What it is: registers the PWA as a handler for certain URL protocols.
Why it matters: lets your app be opened via links such as mailto:, web+music: and other schemes, if the OS and browser allow it.
Practical usage: useful for mail clients, music services, specialized business tools and custom deep‑link scenarios.
Structure: array of objects { protocol, url }. The url must be an HTTPS URL inside the app’s scope. The %s token is replaced with the incoming URL.
Chrome / Chromium: supported, but this is not a baseline feature and depends on the environment.
Safari: not supported or has almost no practical use.
Simple custom protocol example:
{
"protocol_handlers": [
{
"protocol": "web+music",
"url": "/open?uri=%s"
}
]
}
Example with multiple handlers:
{
"protocol_handlers": [
{
"protocol": "web+jngl",
"url": "/lookup?type=%s"
},
{
"protocol": "web+jnglstore",
"url": "/shop?for=%s"
}
]
}
22. related_applications
What it is: a list of applications related to your web app.
Why it matters: you can reference a native Android version, iOS app, Microsoft Store app, or another related PWA.
Practical usage: only makes sense if you actually have another app beyond the web version.
Structure: array of objects { platform, url?, id? }.
Chrome / Chromium: may use this as a hint that related apps exist.
Safari: usually has no visible effect.
Example:
{
"related_applications": [
{
"platform": "play",
"id": "com.example.app",
"url": "https://play.google.com/store/apps/details?id=com.example.app"
}
]
}
Example with multiple platforms:
{
"related_applications": [
{
"platform": "play",
"id": "com.example.app"
},
{
"platform": "webapp",
"url": "https://example.com/manifest.webmanifest"
}
]
}
23. prefer_related_applications
What it is: a hint that a related native app is preferred over installing the PWA.
Why it matters: useful if you want to promote the store app instead of the web installation.
Practical usage: rarely needed for typical PWAs. Makes sense only together with related_applications.
Values: true or false.
Chrome / Chromium: can treat it as a recommendation, not a strict command.
Safari: usually has no noticeable practical impact.
Example:
{
"related_applications": [
{
"platform": "play",
"id": "com.example.app"
}
],
"prefer_related_applications": true
}
24. id
What it is: a unique stable identifier for the app.
Why it matters: helps the browser recognize that it is the same app even if start_url changes over time.
Practical usage: this is considered good modern practice. It is better to set it explicitly instead of relying on start_url as an implicit ID.
Value: string. Typically a path or URL‑like identifier within your project.
Chrome / Chromium: very useful and recommended.
Safari: safe to set even if support is limited.
Examples:
{
"id": "/webappmanifest"
}
{
"id": "/apps/notes"
}
Example together with start_url:
{
"id": "/notes",
"start_url": "/notes/?source=pwa"
}
25. launch_handler
What it is: controls how the app should behave when it is launched.
Why it matters: especially useful on desktop when the app is already open and you need to decide whether to reuse the existing window or open a new one.
Practical usage: needed for advanced desktop PWA scenarios.
Structure: object. At the moment the main field is client_mode.
Chrome / Chromium: experimental.
Safari: not supported.
Example:
{
"launch_handler": {
"client_mode": "navigate-existing"
}
}
Another variant:
{
"launch_handler": {
"client_mode": "auto"
}
}
26. note_taking
What it is: an experimental field that marks the app as a note‑taking application.
Why it matters: the operating system may use it as a hint to integrate the app into “create a note” flows.
Practical usage: only makes sense for note‑taking apps.
Structure: object. One confirmed field is new_note_url.
Important: this field is a hint. Implementations may ignore it or use it in their own way.
Chrome / Chromium: experimental.
Safari: not supported.
Example:
{
"note_taking": {
"new_note_url": "/notes/new"
}
}
27. serviceworker
What it is: a special field for the service worker in a web‑based payment app.
Why it matters: related to the Payment Handler API rather than regular offline PWA behavior.
Practical usage: almost never needed for normal sites and PWAs.
Structure: object for the payment scenario.
Chrome / Chromium: only in a narrow integration with the Payment Handler API.
Safari: not supported.
Generic example:
{
"serviceworker": {
"src": "/payment-sw.js",
"scope": "/",
"use_cache": false
}
}
28. share_target / files
What it is: the nested part of share_target responsible specifically for receiving files.
Why it matters: lets the app receive images, documents and other file types from the system share sheet.
Practical usage: useful for import flows, note apps, media apps, editors and upload tools.
Important: to handle files you must combine method: "POST", enctype: "multipart/form-data" and a files array.
File object structure: each object contains name and accept.
Chrome / Chromium: works for installed PWAs when configured correctly.
Safari: not supported.
Image example:
{
"share_target": {
"action": "/share-target/",
"method": "POST",
"enctype": "multipart/form-data",
"params": {
"files": [
{
"name": "images",
"accept": ["image/png", "image/jpeg"]
}
]
}
}
}
Example for multiple file types:
{
"share_target": {
"action": "/import/",
"method": "POST",
"enctype": "multipart/form-data",
"params": {
"title": "title",
"files": [
{
"name": "documents",
"accept": [".pdf", "application/pdf", ".txt", "text/plain"]
},
{
"name": "images",
"accept": ["image/*"]
}
]
}
}
}
29. protocol_handlers.mailto
What it is: a concrete example of using protocol_handlers for the mailto protocol.
Why it matters: if your PWA acts as a mail interface, you can try to make it a handler for email links.
Practical usage: mostly relevant for mail and communication apps.
Chrome / Chromium: possible as part of the protocol handlers mechanism.
Safari: not supported.
Example:
{
"protocol_handlers": [
{
"protocol": "mailto",
"url": "/compose?to=%s"
}
]
}
Example with multiple protocols:
{
"protocol_handlers": [
{
"protocol": "mailto",
"url": "/compose?to=%s"
},
{
"protocol": "web+message",
"url": "/messages/new?data=%s"
}
]
}