Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 37 ยท Installability and Distribution

The Install Prompt

Build a custom PWA install experience: beforeinstallprompt, appinstalled, display-mode detection, iOS Add to Home Screen guidance, timing and installed-app analytics.

Installing a PWA puts an icon on the home screen, desktop or app launcher and opens the app in its own window without browser chrome. Browsers show their own install controls (an icon in the Chrome address bar, a menu item), but a good PWA also offers an install button at the right moment inside its own interface. This lesson shows how the install events work, how to detect that the app is already installed, what to do on iOS where there is no install event, and when asking is polite.

How the browser decides

On Chromium browsers (Chrome, Edge, Samsung Internet, Opera) the page becomes installable when:

  1. It is served over HTTPS (or from localhost).
  2. A valid web app manifest is linked, with name or short_name, start_url, a display of standalone, fullscreen or minimal-ui, and icons including 192 and 512 pixel sizes.
  3. The user has had some engagement with the site (browsers apply their own heuristics).
  4. The app is not installed already.

When all of this is true, Chromium fires beforeinstallprompt on the window. By default it also shows its own mini-infobar or address bar icon. Your code can capture the event, stop the default prompt and trigger it later from your own button.

Capturing the event

JavaScript
// read-only: install events do not fire inside the sandboxed preview
let deferredPrompt = null;
const installButton = document.querySelector("#install");
installButton.hidden = true;

window.addEventListener("beforeinstallprompt", (event) => {
  event.preventDefault();         // do not show the browser's own prompt yet
  deferredPrompt = event;
  installButton.hidden = false;   // show our button
});

installButton.addEventListener("click", async () => {
  if (!deferredPrompt) return;
  deferredPrompt.prompt();                        // must be called from a user gesture
  const { outcome } = await deferredPrompt.userChoice;   // "accepted" | "dismissed"
  console.log("install choice:", outcome);
  deferredPrompt = null;          // an event can be used only once
  installButton.hidden = true;
});

window.addEventListener("appinstalled", () => {
  installButton.hidden = true;
  deferredPrompt = null;
  // log the install, welcome the user
});

Important details:

  • beforeinstallprompt is not a web standard. Safari and Firefox on desktop do not fire it, so your install button must be hidden by default and appear only when the event fires.
  • prompt() may be called once per event and only from a user gesture such as a click.
  • If the user dismisses the prompt, Chromium waits before firing the event again, so a "dismissed" outcome is a sign to stop asking for a while.

Detecting that the app is running installed

Your page may need to behave differently inside the installed window (for example, hide the "Install" button or the browser-style back link). Use the display-mode media query:

JavaScript
function isInstalled() {
  return (
    window.matchMedia("(display-mode: standalone)").matches ||
    window.matchMedia("(display-mode: fullscreen)").matches ||
    window.matchMedia("(display-mode: minimal-ui)").matches ||
    window.navigator.standalone === true        // iOS Safari only
  );
}

In CSS, the same query styles the app differently when installed:

CSS
@media (display-mode: standalone) {
  .browser-only-link { display: none; }
  body { padding-top: env(safe-area-inset-top); }
}

Try it: an install UI state machine

An install flow has more states than "button visible or not". Writing it as a function keeps it predictable and testable:

JS What should the install UI show?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Safari and iOS

Safari has no install event and no programmatic prompt. Users install through the Share menu: "Add to Home Screen" (iOS and iPadOS) or File, "Add to Dock" (macOS Sonoma and later). From iOS 16.4, an installed web app can also receive push, so guiding users here has real value. Your job is to detect the situation and show short instructions:

JavaScript
const isIos = /iphone|ipad|ipod/i.test(navigator.userAgent) ||
  (navigator.platform === "MacIntel" && navigator.maxTouchPoints > 1);   // iPadOS reports as Mac

if (isIos && !isInstalled()) {
  showHint("Tap the Share button, then 'Add to Home Screen'.");
}

Keep the hint dismissible and remember the dismissal in localStorage. iOS also needs a <link rel="apple-touch-icon" href="/icons/apple-touch-icon.png"> (180 by 180 pixels) so the home screen icon is not a screenshot of the page, plus meta tags such as apple-mobile-web-app-title.

When to ask

The worst place to ask is on first load, before the user knows what your app does. Better triggers:

  • After a success moment: the user finished a task, saved something, read a second article.
  • On the return visit, when the user has already shown interest.
  • When the value of installing is concrete: "Install to read offline", "Install for notifications".

Keep the offer quiet (a small banner or menu entry), explain the benefit in one line, make it easy to close, and respect a "no" for weeks, not minutes.

JS A polite ask: cool-down logic

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Measure installs

Fire an analytics event on appinstalled, and log the userChoice outcome. In installed windows, detect display-mode and send it with page views, so you can compare engagement of installed users with browser users. Also record manifest start_url query parameters such as ?source=pwa to separate launches from the home screen.

  • navigator.getInstalledRelatedApps() tells you whether a related native app (listed in the manifest's related_applications) is installed, so you can avoid asking someone to install the web app when your Android app is already there.
  • The launch_handler manifest member controls whether launching from an icon opens a new window or focuses an existing one.
  • The id manifest member gives the app a stable identity independent of start_url, which matters when you change the start URL later.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why must the install button be hidden by default?

    The event is Chromium-only. The button should appear only when the event arrives.
  2. 2. What must be true to call deferredPrompt.prompt()?

    Browsers require a user gesture for the prompt.
  3. 3. How do you detect that the page runs as an installed app?

    The display-mode media query reflects how the window is presented; iOS adds the legacy navigator.standalone flag.
  4. 4. What is the best moment to suggest installing?

    Asking after value is shown has higher acceptance and does not annoy.

Summary

  • Capture beforeinstallprompt, prevent the default and call prompt() from your own click handler; the event works only once.
  • Treat the event as optional: Safari and Firefox need instructions or the browser menu.
  • Detect installed mode with display-mode and style for it.
  • Ask after value is shown, respect refusals, and measure installs with appinstalled.

Next: Updating a PWA