Add to Home Screen

Add to Home Screen, sometimes referred to as the web app install prompt makes it easy for users to add your Progressive Web App to their app launcher and home screen. Chrome handles most of the heavy lifting for you, and on Android, Chrome will generate a WebAPK creating an even more integrated experience for your users.

What is the criteria?

Chrome will fire the beforeinstallprompt event only when the following criteria are met:

If the web app manifest includes related_applications and has "prefer_related_applications": true, the native app install prompt will be shown instead.

Show the add to home screen prompt

In order to show the Add to Home Screen prompt, you need to:

  1. Listen for the beforeinstallprompt event
  2. Notify the user your app can be installed with a button or other element that will generate a user gesture event.
  3. Show the prompt by calling prompt() on the saved beforeinstallprompt event.

Listen for beforeinstallprompt

If the add to home screen criteria are met, Chrome will fire a beforeinstallprompt event, that you can use to indicate your app can be 'installed', and then prompt the user to install it.

When the beforeinstallprompt event has fired, save a reference to the event, and update your user interface to indicate that the user can add your app to their home screen.

let deferredPrompt;

window.addEventListener('beforeinstallprompt', (e) => {
  // Prevent Chrome 67 and earlier from automatically showing the prompt
  // Stash the event so it can be triggered later.
  deferredPrompt = e;

Notify the user your app can be installed

The best way to notify the user your app can be installed is by adding a button or other element to your user interface. Don't show a full page interstitial or other elements that may be annoying or distracting.

window.addEventListener('beforeinstallprompt', (e) => {
  deferredPrompt = e;
  // Update UI notify the user they can add to home screen = 'block';

In some cases, you may want to wait before showing the prompt to the user, so you don't distract them from what they're doing. For example, if the user is in a check-out flow, or creating their account, let them complete that before interrupting them with the prompt.

Show the prompt

To show the add to home screen prompt, call prompt() on the saved event from within a user gesture. It will show a modal dialog, asking the user to to add your app to their home screen.

Then, listen for the promise returned by the userChoice property. The promise returns an object with an outcome property after the prompt has shown and the user has responded to it.

btnAdd.addEventListener('click', (e) => {
  // hide our user interface that shows our A2HS button = 'none';
  // Show the prompt
  // Wait for the user to respond to the prompt
    .then((choiceResult) => {
      if (choiceResult.outcome === 'accepted') {
        console.log('User accepted the A2HS prompt');
      } else {
        console.log('User dismissed the A2HS prompt');
      deferredPrompt = null;

You can only call prompt() on the deferred event once, if the user dismissed it, you'll need to wait until the beforeinstallprompt event is fired on the next page navigation.

Determine if the app was successfully installed

To determine if the app was successfully added to the users home screen after they accepted the prompt, you can listen for the appinstalled event.

window.addEventListener('appinstalled', (evt) => {
  app.logEvent('a2hs', 'installed');

Detecting if you app is launched from the home screen

display-mode media query

The display-mode media query makes it possible to apply styles depending on how the app was launched, or determine how it was launched with JavaScript.

To apply a different background color for the app above when being launched from the home screen with "display": "standalone", use conditional CSS:

@media all and (display-mode: standalone) {
  body {
    background-color: yellow;

It's also possible to detect if the display-mode is standalone from JavaScript:

if (window.matchMedia('(display-mode: standalone)').matches) {
  console.log('display-mode is standalone');


To determine if the app was launched in standalone mode in Safari, you can use JavaScript to check:

if (window.navigator.standalone === true) {
  console.log('display-mode is standalone');

Updating your app's icon and name

If you change any of the properties in your manifest, those changes will be reflected to the user after they've run your app again.

Test your add to home screen experience

You can manually trigger the beforeinstallprompt event with Chrome DevTools. This makes it possible to see the user experience, understand how the flow works or debug the flow. If the PWA criteria aren't met, Chrome will throw an exception in the console, and the event will not be fired.

Chrome for Android

  1. Open a remote debugging session to your phone or tablet.
  2. Go to the Application panel.
  3. Go to the Manifest tab.
  4. Click Add to home screen

Chrome OS

  1. Open Chrome DevTools
  2. Go to the Application panel.
  3. Go to the Manifest tab.
  4. Click Add to home screen

Will beforeinstallprompt be fired?

The easiest way to test if the beforeinstallprompt event will be fired, is to use Lighthouse to audit your app, and check the results of the User Can Be Prompted To Install The Web App test.