What Is the Beforeinstallprompt Event
The beforeinstallprompt event is a window-level event that fires when the browser has detected that a website can be installed as a Progressive Web App. Unlike the default browser installation prompt, which appears automatically and with limited customization options, this event gives developers the opportunity to intercept the installation flow and implement their own user experience.
The event fires when several conditions are met: the web application has a valid web app manifest with required fields including name and icons, the application is served over HTTPS, and the user has visited the site for a sufficient amount of time. Importantly, there is no guaranteed timing for when this event fires--it may occur on page load, after some user interaction, or potentially not at all if the browser determines the user is not a good candidate for installation prompts.
For developers building AI-powered applications, custom installation flows provide an opportunity to explain how offline access and faster interactions enhance the AI experience. This is particularly valuable for agentic workflows that benefit from reliable background operation and persistent conversation context.
When working with DOM manipulation for custom installation UIs, understanding the Fragment API can help you efficiently build and insert installation prompts into the document structure without triggering unnecessary reflows.
Event Lifecycle and Firing Conditions
Understanding when and why the beforeinstallprompt event fires requires knowledge of the browser's installation detection process. Modern browsers evaluate multiple factors before determining whether an application is eligible for installation and whether the user should be prompted.
Technical Requirements
The browser considers several technical requirements first. The application must be served over a secure origin (HTTPS) to ensure that the manifest and associated resources can be trusted. The manifest file must include essential fields such as name, short_name, and at least one icon with appropriate sizes. The application must include a registered service worker, which demonstrates the app's capability to work offline--a key characteristic of Progressive Web Apps.
Browser Heuristics
Beyond these technical requirements, browsers apply their own heuristics to determine when to fire the event. These heuristics aim to balance installation accessibility with user experience, avoiding prompts that might annoy users who have no intention of installing the application. Some browsers may delay firing the event until the user has demonstrated engagement with the application, such as spending time on multiple pages or interacting with key features.
Implementing custom installation flows requires understanding these heuristics to provide the best user experience. When you work with our web development team, we ensure your PWA meets all requirements while respecting browser guidelines.
The Storage Manager API provides additional capabilities for managing persistent storage on user devices, which complements the installation experience by ensuring your PWA has adequate storage space for offline data. See how the Storage Manager API works alongside PWA installation.
Browser Support and Compatibility
Browser support for the beforeinstallprompt event varies significantly across the landscape, which has important implications for how developers should approach custom installation flows.
Current Support Status
As of 2025, Chromium-based browsers including Google Chrome, Microsoft Edge, and Opera provide full support for the beforeinstallprompt event. This means that users of these browsers can benefit from custom installation experiences implemented by developers. However, Mozilla Firefox and Apple Safari do not support this event, which limits the ability to customize installation flows for users of these browsers.
Progressive Enhancement Approach
The limited availability of this feature means developers should implement feature detection and provide fallback experiences. A common approach is to detect whether the event is available and, if not, allow the browser's default installation prompt to function normally or simply not show an installation option.
| Browser | Support Status |
|---|---|
| Chrome | Full Support |
| Edge | Full Support |
| Firefox | Not Supported |
| Safari | Not Supported |
| Opera | Full Support |
For cross-browser compatibility, we recommend implementing feature detection and providing alternative experiences for users on unsupported browsers. Our web development services include comprehensive browser compatibility testing to ensure your PWA works reliably across all platforms.
The BeforeInstallPromptEvent Interface
The BeforeInstallPromptEvent interface provides the programmatic tools necessary to implement custom installation flows. Understanding its properties and methods is essential for proper implementation.
Event Properties
The event interface includes several important read-only properties that provide information about the installation options available to the user.
platforms property: Returns an array of strings representing the platforms on which the application can be installed. This array might include values such as "web" for the web application itself, "play" for Android installation via Google Play Store, or other platform-specific identifiers depending on the browser and device.
userChoice property: Returns a Promise that resolves to an object describing the user's choice when they were prompted to install the application. This promise resolves after the user has responded to the installation prompt, providing developers with valuable feedback about the outcome.
Event Methods
The primary method available on the BeforeInstallPromptEvent interface is the prompt() method, which displays the browser's installation prompt to the user. This method returns a Promise that resolves to the same object structure as the userChoice property.
Unlike the default browser behavior, calling prompt() allows developers to defer showing the installation prompt until a strategic moment. This flexibility is essential for optimizing user engagement and maximizing installation acceptance rates.
The Sync API complements the installation experience by enabling background synchronization of data, ensuring your installed PWA maintains fresh content even when the user is offline. Learn more about background sync capabilities for PWAs.
1let deferredPrompt;2const installButton = document.getElementById('install-button');3 4// Listen for the beforeinstallprompt event5window.addEventListener('beforeinstallprompt', (event) => {6 // Prevent the browser's default installation prompt7 event.preventDefault();8 9 // Store the event for later use10 deferredPrompt = event;11 12 // Update UI to indicate installation is available13 installButton.removeAttribute('hidden');14});15 16// Handle installation when user clicks the button17installButton.addEventListener('click', async () => {18 if (!deferredPrompt) {19 return;20 }21 22 // Show the installation prompt23 const result = await deferredPrompt.prompt();24 25 // Log the user's choice26 console.log(`Installation outcome: ${result.outcome}`);27 console.log(`Platform: ${result.platform}`);28 29 // Clear the stored event30 deferredPrompt = null;31 32 // Hide the install button since the prompt was shown33 installButton.setAttribute('hidden', '');34});Best Practices for Installation UX
Creating an effective installation experience requires balancing multiple factors: user education, timing, visual presentation, and respect for user preferences.
Timing Your Installation Prompt
One of the most important decisions in custom installation flows is determining when to show the installation prompt. Presenting the prompt too early--before the user understands the application's value--typically results in low acceptance rates.
Effective timing strategies include waiting until the user has completed a key action that demonstrates the application's utility, such as creating their first document or completing a transaction. Another approach is to wait for signs of engagement, such as multiple page visits or a minimum session duration.
Educating Users About Installation
Users may not understand what it means to install a Progressive Web Application or what benefits they will receive. Custom installation flows provide the opportunity to explain these benefits in context:
- Offline access to key features
- Faster loading from the home screen
- Integration with the operating system
- Push notification capabilities
- Full-screen immersive experience
Respecting User Choices
If a user dismisses the installation prompt, it is important to respect that decision. Avoid repeatedly showing installation prompts, as this creates a negative user experience and may lead to frustration or disengagement.
Progressive Enhancement
Since the beforeinstallprompt event is not supported in all browsers, implement your installation feature with progressive enhancement:
// Feature detection
if ('BeforeInstallPromptEvent' in window) {
// Set up custom installation flow
window.addEventListener('beforeinstallprompt', handleInstallPrompt);
} else {
// Fall back to default behavior or hide install option
}
Our team follows these best practices to ensure your PWA installation flow delivers exceptional user experience while respecting browser capabilities and user preferences.
Integration with LLM-Powered Applications
For developers building applications powered by large language models, the beforeinstallprompt event offers opportunities to enhance the user experience of agentic applications and AI-driven interfaces.
Enabling Offline Access for AI Features
LLM-powered applications often involve complex interactions that benefit from reliable performance. By enabling installation through the beforeinstallprompt event, you can ensure users have offline access to cached responses and cached model capabilities:
- Pre-loaded prompts and response templates
- Cached conversation history for context
- Offline access to frequently used tools
- Faster interactions for common requests
Enhancing Agent Workflows
For agentic applications that automate multi-step workflows, installation provides a more reliable environment for background operations. Installed PWAs can utilize service workers to handle background synchronization, ensuring that agent workflows continue even when the browser is closed.
Managing Resource Constraints
LLM interactions can be resource-intensive, and installation can help manage these constraints through caching strategies. By implementing custom installation flows, developers can educate users about how installation helps with reducing latency for common queries, managing API usage through local processing, providing persistent conversation context, and enabling offline fallback for AI features.
If you're building AI-powered applications, our team can help you implement installation flows that maximize user engagement and provide seamless access to your AI capabilities. We specialize in custom web development that integrates advanced features like offline support and background synchronization.
Troubleshooting Common Issues
When implementing the beforeinstallprompt event, developers frequently encounter issues that can be traced to specific causes.
Event Not Firing
If the beforeinstallprompt event is not firing, check these common causes:
- The application is not served over HTTPS (or localhost for development)
- The web app manifest is missing required fields (name, icons)
- The manifest URL is incorrect or inaccessible
- No service worker is registered
- The user has already installed the application
- The browser has determined the user is not a candidate for prompts
Install Button Not Working
If the custom install button does not trigger the prompt, verify that the event object is properly stored and not null, the prompt() method is being called correctly, the button is not being disabled or obscured by CSS, and no errors are occurring in the click handler.
Single-Use Constraint
A critical constraint of the beforeinstallprompt event is that the prompt() method can only be called once per event instance. After the user responds to the prompt, the event is consumed and cannot be used again. You must wait for a new event to fire for another installation attempt.
For comprehensive debugging and implementation support, our development team can help identify and resolve any issues with your PWA installation flow.
Frequently Asked Questions
Sources
- MDN Web Docs: Window beforeinstallprompt event - Authoritative documentation for web APIs
- Microsoft Edge Developer: Best practices for PWAs - Official Microsoft guidance on PWA best practices
- Can I Use: beforeinstallprompt browser support - Browser compatibility reference
- WICG Manifest Incubations Specification - Official specification for the beforeinstallprompt attribute