Skip to content

Concept in Installation

PWA install criteria: menu installs and prompts

Published Updated

Installability criteria are the conditions a browser checks before it proactively offers an install surface for a page, such as an address-bar icon or the beforeinstallprompt event; some browsers also let users install by hand from a menu without meeting them. Chromium browsers (Chrome, Edge, Samsung Internet) gate on a secure origin plus a manifest with a name, a start URL, a non-browser display mode, and icons; Chrome and desktop Edge also let users install a page without a manifest by hand, while WebKit says Safari on iOS 26 has no installability requirements and Firefox 143 on Windows pins sites as taskbar web apps without documenting one (BCD manifests.webapp, Chrome “Changes to the installability criteria”, WebKit Safari 26.0 release post, Firefox 143 release notes).

The Application › Manifest panel in Chrome DevTools shows an Installability section that describes install errors, such as an icon that cannot be loaded. The checks below follow Chrome’s install-criteria article, though the article orders them differently (not already installed, user engagement, HTTPS, then the manifest members):

  • The page is served from a secure context: https:; http://localhost and http://127.0.0.1 also qualify during development.
  • The document links a manifest (<link rel="manifest">) that parses and contains name or short_name, start_url, a display of standalone, fullscreen, or minimal-ui (or a display_override that resolves to one), and icons including a 192 px and a 512 px entry; for the install dialog Chrome requires at least one icon of 144 px or larger in PNG, SVG, or WebP with sizes set and purpose including any.
  • start_url is within scope and returns a document (a redirect to another origin fails the check).
  • prefer_related_applications is absent or false.
  • The app is not already installed in this browser profile.

A registered service worker with a fetch handler was part of the list until Chrome 108 on Android and Chrome 112 on desktop removed it for installation from the browser menu; Chrome supplies a default offline page for installed apps without one. That historical post also described a fetch-handler check for the prompt at the time; the currently published checklist no longer lists it. Chrome additionally delays the event (and the Android mini-infobar) until its engagement heuristics are met, which is why the DevTools panel can report “installable” while no event fires.

Other browsers apply different lists:

Browser What it requires before offering install Install surface
Edge (desktop) The same manifest members as Chrome (MDN); Chrome’s release floors (108 on Android, 112 on desktop) are Chrome versions Install from the browser menu, with or without a manifest (MDN)
Samsung Internet The same manifest members as Chrome (MDN) beforeinstallprompt (BCD records it from 5.0)
Safari, iOS and iPadOS 26 None: every site added from the Share sheet opens as a web app unless the user turns off “Open as Web App” Share sheet › “Add to Home Screen”
Safari, iOS and iPadOS 16.4 to 18 Manifest display: standalone or fullscreen (or the legacy apple-mobile-web-app-capable meta tag) for web-app mode; otherwise a bookmark Share sheet › “Add to Home Screen”
Safari 17+, macOS 14+ None; File › “Add to Dock” works for any page, manifest values are used when present File menu
Firefox 143+, Windows None documented; the release notes describe websites pinned to the taskbar as web apps, and say the feature is not currently available for installs from the Microsoft Store Not documented in the release notes
Firefox for Android A manifest; installs as a home-screen shortcut, no event Three-dot menu › “Install”

Passing a manifest checklist does not guarantee installation on another browser. Test the intended install path on the target browser and operating system. Menu installation and an automatic install promotion are separate behaviours; a missing event does not prove that the menu path is unavailable.

You can check the inputs a page controls and supply a manifest that meets Chromium’s requirements.

Checking an app without promising an install event

Section titled “Checking an app without promising an install event”

Use Chrome DevTools to inspect the manifest, then test the browser menu separately from your in-page install button. A short page script cannot reproduce the browser’s full decision: user engagement and prior installation also affect promotion. Testing whether onbeforeinstallprompt exists is not evidence that the event will fire for the current page.

For a useful troubleshooting record:

  1. Record the browser version, operating system and whether the app is already installed in this profile.
  2. Open Application › Manifest and resolve reported parsing or icon-loading errors. Check the final manifest response, including its HTTP status; a JSON error response is not a valid app manifest.
  3. Check the menu’s install action. Record whether it is absent, opens a shortcut flow, or installs an app.
  4. Test your beforeinstallprompt listener separately. Only enable a button that calls prompt() after receiving and saving an actual event. See the install prompt example.
  5. Test offline navigation as its own capability. The existence of navigator.serviceWorker shows API support; it does not establish that a worker is registered, controls this page, or has cached a usable response.

Chrome’s current published checklist lists engagement, HTTPS and manifest requirements without a service-worker requirement. Its older change announcement described a fetch-handler check for the prompt at that time. Do not treat that historical statement as a universal requirement for every current browser build.

The example supplies common Chromium install-promotion fields. It is a starting point for validation on a real origin, not a cross-browser installation guarantee. Its URLs and icon files must exist on your site.

{
"name": "Field Notes",
"short_name": "Notes",
"id": "/notes/",
"start_url": "/notes/?source=pwa",
"scope": "/notes/",
"display": "standalone",
"background_color": "#ffffff",
"theme_color": "#1f3a5f",
"icons": [
{ "src": "/notes/icons/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" },
{ "src": "/notes/icons/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" },
{ "src": "/notes/icons/maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
]
}

Use separate icon entries for the any and maskable purposes. Chrome’s dialog needs an icon whose purpose includes any; a single entry with "purpose": "any maskable" passes the check but renders the same bitmap in both contexts.

Specifications

SpecificationStatus
None.