BeforeInstallPromptEvent: Customizing PWA Installation Prompts

Take control of the installation experience for your Progressive Web App using the BeforeInstallPromptEvent API

What is BeforeInstallPromptEvent?

The BeforeInstallPromptEvent is an interface that fires at the Window object before a user is prompted to install a website to a home screen on mobile devices. This event serves as a gateway between the browser's installation detection mechanism and the user's decision-making process, giving developers unprecedented control over when and how installation opportunities are presented.

When a Progressive Web App meets the installation criteria--which includes having a valid web app manifest, being served over HTTPS, and having a registered service worker--the browser recognizes it as installable. The BeforeInstallPromptEvent intercepts this default behavior, allowing developers to prevent the automatic prompt and instead store the event for later use.

The event inherits from the standard Event interface, meaning it carries the familiar event object properties and methods developers already work with regularly. This inheritance provides familiar patterns for event handling while introducing PWA-specific functionality through additional properties and methods designed specifically for installation management.

Event Lifecycle Overview

Understanding the event lifecycle is crucial for effective implementation. The lifecycle begins when the browser determines that a website qualifies as installable:

  1. Browser detects installable PWA and fires beforeinstallprompt event
  2. Developer listens for the event and calls preventDefault() to intercept
  3. Event object is stored for later access
  4. Developer triggers prompt() method when user engages with custom install UI

This three-phase approach--capture, store, trigger--forms the foundation of custom installation experiences and enables sophisticated user engagement strategies that would be impossible with default browser behavior alone.

Capturing the beforeinstallprompt Event
1let deferredPrompt;2 3window.addEventListener('beforeinstallprompt', (event) => {4 // Prevents the default mini-infobar from appearing5 event.preventDefault();6 // Stash the event so it can be triggered later7 deferredPrompt = event;8 // Update UI to show the install button9 installButton.removeAttribute('hidden');10});

Key Properties and Methods

The platforms Property

The platforms property returns an array of string items containing the platforms on which the event was dispatched. This information proves valuable for applications that might offer installation options across different platforms, such as allowing users to choose between a web installation or a native Android app alternative.

The array might contain values like "web" to indicate a Progressive Web App installation, or other platform-specific identifiers depending on the browser and context. By examining this property, developers can customize their installation messaging based on the available options, providing clearer guidance to users about what installation means on their particular device and browser combination.

The userChoice Property

The userChoice property returns a Promise that resolves to an object describing the user's choice. The resolved object contains:

  • outcome: Whether the user accepted or dismissed the prompt
  • platform: The selected platform identifier (if applicable)

This asynchronous property enables developers to track installation outcomes and adjust their application behavior accordingly. The outcome information proves invaluable for analytics, user experience optimization, and understanding engagement patterns around application installation. Implementing robust SEO analytics alongside this tracking helps measure the full conversion funnel from discovery to installation.

The prompt() Method

The prompt() method shows the install prompt at a developer-chosen time. It must be called in response to a user action (such as a button click) and may only be called once per event instance. When called, the prompt() method returns a Promise resolving to an object containing the outcome property, which indicates whether the user chose to install the app ("accepted") or not ("dismissed").

Triggering the Installation Prompt
1installButton.addEventListener('click', async () => {2 if (!deferredPrompt) {3 return;4 }5 // Show the prompt6 const result = await deferredPrompt.prompt();7 8 // Log the outcome for analytics9 console.log(`Install prompt was: ${result.outcome}`);10 11 // Clear the stored prompt12 deferredPrompt = null;13 14 // Hide the install button15 installButton.setAttribute('hidden', '');16});
BeforeInstallPromptEvent Benefits

Why customize the installation experience

Strategic Timing

Show the install prompt when users are most engaged and understand your app's value

Better UX

Create cohesive install flows that match your application's design language

Analytics Insight

Track installation outcomes and optimize your conversion rates

User Control

Let users choose when to install rather than interrupting their experience

Browser Compatibility

The BeforeInstallPromptEvent is supported in Chromium-based browsers (Chrome, Edge) but does not have widespread support in Firefox or Safari. The API is marked as experimental and non-standard, having been moved from the Web App Manifest specification to a separate incubation working group.

Progressive Enhancement Strategy

Given limited browser support, implement progressive enhancement:

  • Detect support for the beforeinstallprompt event
  • Show custom install UI only in supporting browsers
  • Provide fallback instructions for unsupported browsers
  • Always rely on the browser's default behavior as a baseline

Best Practices

  1. Time your prompts strategically - Wait until users demonstrate engagement before asking to install
  2. Communicate value - Explain benefits of installation in your custom UI
  3. Respect user choice - Do not repeatedly prompt after dismissal
  4. Track outcomes - Use the userChoice property to understand conversion rates

The key principle is that the user should understand the application's value proposition before being asked to install it. Common effective timing strategies include prompting after the user completes a significant action, such as creating an account or completing a task, or after the user has returned to the application multiple times, indicating sustained interest. PWAs represent a powerful intersection of web and native app experiences--our AI automation services can help you build intelligent features that work seamlessly within installable web applications.

Frequently Asked Questions

Can I call prompt() multiple times?

No, the prompt() method may only be called once on a given BeforeInstallPromptEvent instance. After calling it, the event is consumed and cannot be used again.

What happens if the user dismisses the prompt?

When the user dismisses the prompt, the result.outcome will be 'dismissed'. You can listen for the event again on future page visits to offer installation again.

Do I need a service worker for this to work?

Yes, having a registered service worker is one of the PWA installation criteria. The beforeinstallprompt event will not fire without one.

Can I customize the installation dialog itself?

No, the actual installation dialog is controlled by the browser and cannot be customized. You can only control when it appears, not its content or appearance.

Ready to Build Progressive Web Apps?

Our team specializes in building modern web applications with advanced capabilities like PWAs, offline functionality, and installable experiences that drive user engagement.

Sources

  1. MDN Web Docs: BeforeInstallPromptEvent - Core API reference covering constructor, properties, methods
  2. web.dev: Installation Prompt - Implementation guide with code examples and best practices
  3. MDN: prompt() method - Technical specification of the prompt() method