The beforeinstallprompt event: a 2026 field guide

beforeinstallprompt is the browser telling you: "I would let this user install your PWA — do you want to say something first?" Handling it well is the difference between a 0.5% and a 6% install rate.

The lifecycle

Chromium browsers fire the event when engagement heuristics are met (HTTPS, manifest, service worker, ~30s dwell or two visits). You get a BeforeInstallPromptEvent with two members: prompt() and userChoice.

let deferred = null;
window.addEventListener('beforeinstallprompt', (e) => {
  e.preventDefault();
  deferred = e;
  showYourOwnInstallButton();
});

Triggering later

The prompt() call must happen inside a user-gesture handler (click, keydown). Firing it from a setTimeout throws NotAllowedError.

installBtn.addEventListener('click', async () => {
  if (!deferred) return;
  deferred.prompt();
  const { outcome } = await deferred.userChoice;
  analytics.track('install_prompt', { outcome }); // 'accepted' | 'dismissed'
  deferred = null;
});

When it will not fire

• Already installed (display-mode: standalone).
• Manifest missing name, icons (192 + 512), start_url, or display: standalone/minimal-ui.
• Service worker doesn’t handle a fetch for start_url.
• User dismissed the mini-infobar twice in 90 days.
• iOS Safari — the event does not exist. You must render a share-sheet guide.

Related events worth listening for

appinstalled fires once install completes — the correct place to record the conversion. DOMContentLoaded is too early to check navigator.getInstalledRelatedApps(); wait for load.

Pattern we recommend

Capture the deferred event on load. Do not show a button immediately — wait for a natural moment (second pageview, item saved). Fire your own popup that explains the benefit; if the user clicks Install, call prompt(). If Chrome never fires the event, fall back to the manual iOS-style guide.

InstantPWA handles all of this — deferred event capture, gesture routing, iOS fallback, and analytics — behind a single script tag.