Concept in Installation
Install prompt UX
Published Updated
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.
How it works
Section titled “How it works”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.
Examples
Section titled “Examples”Keep the install action tied to the retained event. Check display mode separately; it cannot establish installation in all cases.
Revealing a button only after the event
Section titled “Revealing a button only after the event”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.
Observed behaviour
Section titled “Observed behaviour”The manual fallback can point to those documented labels when its maintained instructions identify Safari 26 on iOS or iPadOS.
See also
Section titled “See also”- How to provide your own in-app install experience (web.dev)
- Window: beforeinstallprompt event (developer.mozilla.org)
- beforeinstallprompt event
- Installability criteria
- iOS Add to Home Screen
- Desktop installation
Specifications
| Specification | Status |
|---|---|
| Install Prompt (beforeinstallprompt) | WICG draft |
- Legend
- Yes
- Partial
- Flag
- No
- Unknown
| Browser / Platform | Support | Versions | Confidence | Source | Notes |
|---|---|---|---|---|---|
| Chrome (Desktop)# | Yes | 44 | high | source | — |
| Chrome (Android)# | Yes | 44 | high | source | 1 |
| Edge (Desktop)# | Yes | 79 | high | source | 2 |
| Firefox (Desktop)# | No | — | high | source | 3 |
| Firefox (Android)# | No | — | high | source | 45 |
| Safari (macOS)# | No | — | high | source | 6 |
| Safari (iOS)# | No | — | high | source | 78 |
| Samsung Internet# | Yes | 5.0 | high | source | — |
| WebView (Android)# | Yes | 44 | high | source | 9 |
- Derived by browser-compat-data mirroring from Chrome.
- Derived by browser-compat-data mirroring from Chrome.
- No Firefox support is recorded in browser-compat-data.
- No Firefox for Android support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Firefox.
- No Safari support is recorded in browser-compat-data.
- No Safari on iOS support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Safari.
- Derived by browser-compat-data mirroring from Chrome Android.
Try it
Run this capability in the OpenPWA demo app: /demo/#install