Understanding the Install Prompt
You'll learn: When and why browsers display the native "Add to Home Screen" prompt for your Progressive Web App.
What Triggers the Install Prompt?
The beforeinstallprompt event is the browser's way of telling you, "Hey, this web app meets the installability criteria—I'm ready to let the user add it to their device." This event doesn't fire randomly; browsers have specific requirements:
- Your app must have a valid Web App Manifest (with name, icons, start_url, and display mode)
- A Service Worker must be registered and active
- The site must be served over HTTPS
- The user hasn't already installed your app
- The user has engaged with your site (varies by browser—often after 30 seconds or multiple visits)
Think of it like a bouncer at a club: your PWA needs to meet all entry requirements before the browser even considers showing the install option.
Controlling When Users See It
By default, browsers show their own install prompt automatically when these criteria are met. However, you can listen for beforeinstallprompt, call preventDefault() on it, and store the event object. This lets you show your own custom install button at a more contextually appropriate moment—like after a user completes a key action or shows clear engagement.
When you're ready, you call the stored event's .prompt() method to trigger the native browser dialog.
Browser Behavior Varies
Chrome, Edge, and Samsung Internet support this flow reliably. Safari on iOS handles installation differently (through the Share menu), and doesn't fire beforeinstallprompt. Always test across browsers and provide fallback instructions.
Key Takeaway: The beforeinstallprompt event signals that your PWA meets installability criteria, and capturing it lets you control when users see your custom install prompt instead of relying on automatic browser timing.