Definition

beforeinstallprompt userChoice

Short definition

userChoice is a property on the deferred beforeinstallprompt event, resolving to an object like { outcome: "accepted" | "dismissed", platform: "web" }, available after calling deferredEvent.prompt(). It is the only reliable, synchronous-feeling signal for whether a user actually accepted or dismissed your custom install prompt in that specific interaction.

Reviewed August 11, 2026

Typical usage: deferredEvent.prompt(); const { outcome } = await deferredEvent.userChoice; if (outcome === "accepted") { /* log conversion */ } else { /* maybe suppress the CTA for a while */ }.

The captured event object is single-use — after userChoice resolves, calling prompt() again on the same event instance throws, so a site wanting to prompt again later must wait for a fresh beforeinstallprompt event on a future page load.

outcome: "dismissed" covers both the user explicitly clicking "Cancel" and simply closing the dialog without choosing, so it cannot distinguish an active rejection from an ignored prompt — some teams track dismiss frequency to decide when to stop showing their own install CTA rather than trying to interpret dismissal intent further.

userChoice measures the outcome of your own custom install button, not installs completed via the browser's own address-bar icon or menu — appinstalled is the complementary signal that catches those paths too.

Related terms

appinstalled event

appinstalled is a window event, listened for with window.addEventListener("appinstalled", () => { ... }), that fires after the browser has finished installing the PWA — regardless of whether the install was triggered via the native beforeinstallprompt flow or a browser menu item. It fires exactly once per successful install and carries no event detail beyond the fact that installation completed.

PWA install criteria

Chromium's PWA install criteria require: the site served over HTTPS; a linked Web App Manifest with at least a name (or short_name), a 192x192 and 512x512 icon, a start_url, and a display value of standalone, fullscreen, minimal-ui or a display_override entry; and a registered service worker with a fetch event handler, even a minimal pass-through one.

id (manifest field)

id is a manifest field, for example "id": "/app-v1", used as the app's permanent identifier for the OS install registry. Unlike start_url, id is not meant to change; if it is omitted, the browser derives an identity from start_url instead, which means later changing start_url can register as a brand-new app.

Service worker

A service worker is a JavaScript file the browser runs in the background, separate from the page. It intercepts network requests, caches responses so the site works offline, and receives web-push events so the site can notify the user when it is closed.

Web App Manifest

A Web App Manifest is a JSON file (usually manifest.webmanifest) that declares your app's name, icons, start URL, theme colour and display mode. The browser reads it to render the install prompt and the home-screen icon.

beforeinstallprompt

beforeinstallprompt is a window event Chromium browsers fire when a site meets the PWA install criteria. Capturing the event and calling prompt() later lets you show the install dialog at a moment of your choosing instead of at page load.