Skip to content

Concept in Installation

Install prompt UX

Published Updated

Limited availabilityNot supported in Firefox (Desktop), Firefox (Android), Safari (macOS), Safari (iOS)WICG draft

An install prompt lets users install a PWA from a page. You can choose when to show a custom install button and what help to offer when no programmatic prompt is available. The custom button depends on the limited-availability beforeinstallprompt event, while the fallback leaves installation to browser-provided UI.

The site’s install button starts hidden. When beforeinstallprompt fires, the handler can call preventDefault(), retain the event, and reveal the button. A later click calls the retained event’s prompt() method. web.dev states that a retained event can be used only once, so the page clears it after prompting (How to provide your own in-app install experience, web.dev).

Firefox and Safari do not support BeforeInstallPromptEvent, according to browser-compat-data. Keep a browser-provided installation path available when using the event to enhance your install flow.

The display-mode media feature reports the display mode being used. MDN documents values including browser, standalone, minimal-ui, fullscreen, and window-controls-overlay. A match for one value describes the active display mode; it does not by itself prove every possible installed state.

Keep the install action tied to the retained event. Check display mode separately; it cannot establish installation in all cases.

Keep the browser’s own UI available when the event is absent, and clear the retained event after use.

<button id="install" type="button" hidden>Install app</button>
<script>
const installButton = document.querySelector('#install');
let deferredInstall;
window.addEventListener('beforeinstallprompt', (event) => {
event.preventDefault();
deferredInstall = event;
installButton.hidden = false;
});
installButton.addEventListener('click', async () => {
if (!deferredInstall) return;
await deferredInstall.prompt();
deferredInstall = undefined;
installButton.hidden = true;
});
window.addEventListener('appinstalled', () => {
deferredInstall = undefined;
installButton.hidden = true;
});
</script>

If no beforeinstallprompt event arrives, the button remains hidden.

Selecting an in-app message or a manual fallback

Section titled “Selecting an in-app message or a manual fallback”

Feature detection decides whether to wait for the event. For the fallback, render browser-specific help from maintained instructions. Avoid guessing menu labels in JavaScript.

const standalone = window.matchMedia('(display-mode: standalone)').matches;
const canReceivePrompt = 'onbeforeinstallprompt' in window;
if (standalone) {
hideInstallPromotion();
} else if (canReceivePrompt) {
keepInstallButtonHiddenUntilEvent();
} else {
showManualInstallHelp();
}

Handle an absent event explicitly. If your app supports additional installed display modes, test those modes separately.

The manual fallback can point to those documented labels when its maintained instructions identify Safari 26 on iOS or iPadOS.

Specifications

SpecificationStatus
Install Prompt (beforeinstallprompt)WICG draft
  • Legend
  • Yes
  • Partial
  • Flag
  • No
  • Unknown
Browser / PlatformSupportVersionsConfidenceSourceNotes
Chrome (Desktop)#Yes44highsource—
Chrome (Android)#Yes44highsource1
Edge (Desktop)#Yes79highsource2
Firefox (Desktop)#No—highsource3
Firefox (Android)#No—highsource45
Safari (macOS)#No—highsource6
Safari (iOS)#No—highsource78
Samsung Internet#Yes5.0highsource—
WebView (Android)#Yes44highsource9
  1. Derived by browser-compat-data mirroring from Chrome.
  2. Derived by browser-compat-data mirroring from Chrome.
  3. No Firefox support is recorded in browser-compat-data.
  4. No Firefox for Android support is recorded in browser-compat-data.
  5. Derived by browser-compat-data mirroring from Firefox.
  6. No Safari support is recorded in browser-compat-data.
  7. No Safari on iOS support is recorded in browser-compat-data.
  8. Derived by browser-compat-data mirroring from Safari.
  9. Derived by browser-compat-data mirroring from Chrome Android.

Source data: /compatibility/install-prompt.json · Global usage: 75 % (StatCounter 2026-09, CC BY-SA 4.0)

Source: spec · MDN · Last verified 2026-10-20 · Confidence: high (computed from sources)