beforeinstallprompt Event Capture Debugger

Introduction

The beforeinstallprompt event allows a website to delay the browser’s default install prompt and present a custom install button instead. This is useful when you want control over when and how users are invited to install your progressive web app.

The event can be confusing because it only fires under specific conditions, and it may not fire at all if the page is already installed, does not meet installability requirements, or runs in a browser that does not support the event.

How it works

This tool listens for real browser events on the current page. It also provides a synthetic event mode so you can test the button and prompt flow without relying on installability.

• Real events are captured with window.addEventListener("beforeinstallprompt", ...).
• The event is stored so it can be triggered later from a user click.
• Synthetic events are clearly labeled and only simulate UI behavior.
• The generated snippet uses standard DOM APIs and does not rely on frameworks.

How to use

1. Open this page in a browser that supports beforeinstallprompt.
2. Watch the event log for a real event.
3. If no real event appears, use Create synthetic event to test the UI flow.
4. Click Trigger captured prompt when an event is available.
5. Use the snippet generator to create a custom install button for your own site.
6. Test the snippet on your own HTTPS-enabled PWA.

Practical example

The generated snippet follows this pattern:

window.addEventListener("beforeinstallprompt", (event) => {
  event.preventDefault();
  deferredPrompt = event;
  button.hidden = false;
});

button.addEventListener("click", async () => {
  if (!deferredPrompt) {
    return;
  }

  deferredPrompt.prompt();
  await deferredPrompt.userChoice;
  deferredPrompt = null;
});

This keeps the prompt deferred until the user chooses to install.

Use cases

• Debugging why a custom install button never appears.
• Testing whether your app captures the install event.
• Prototyping install UX before final PWA requirements are complete.
• Generating clean install button code without a framework.
• Explaining the event flow to teammates or clients.

Best practices

• Always call event.preventDefault() when storing the event.
• Only call prompt() after a user gesture.
• Hide the install button until the event is captured.
• Listen for appinstalled to update your UI after installation.
• Do not repeatedly prompt users after dismissal.

Common mistakes

• Calling prompt() outside a click handler.
• Assuming the event fires on every browser.
• Forgetting HTTPS or service worker requirements.
• Showing the install button before the event exists.
• Treating synthetic tests as proof of real installability.

Limitations

• This tool cannot force a real browser event to fire.
• Synthetic events do not install anything.
• Browser support varies, especially on iOS.
• The tool cannot inspect another website’s page directly.
• Real installability depends on your live site, manifest, service worker, and HTTPS.

Browser compatibility

• Chrome and Edge: Primary support for beforeinstallprompt.
• Firefox: Does not use the same install prompt model.
• Safari: iOS and macOS use Add to Home Screen behavior rather than this event.

FAQ

Related tools

• PWA Manifest Installability Predictor
• Web Share Target API Manifest Generator
• Service Worker Cache Strategy Simulator
• Push Notification Payload Builder

References

• MDN Web Docs: Window: beforeinstallprompt event
• Chrome Developers: Debug progressive web apps
• web.dev: Progressive Web Apps

Version and changelog

• Version: 1.0.0
• Last updated: August 8, 2026
• Changelog: Initial production release.