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.

What is the criteria?

Chrome will automatically show the Add to Home Screen prompt to the user when the following criteria are met:
  • The web app is not already installed
  • Meets a user engagement heuristic (currently, the user has interacted with the domain for at least 30 seconds)
  • Meets the Progressive Web App criteria:
    • Includes a web app manifest that includes:
      • short_name or name
      • icons including a 192px and a 512px version
      • start_url
    • Served over HTTPS (required for service workers)
    • Has registered a service worker with a fetch event handler
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
  e.preventDefault();
  // 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) => {
  e.preventDefault();
  deferredPrompt = e;
  // Update UI notify the user they can add to home screen
  btnAdd.style.display = '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
  btnAdd.style.display = 'none';
  // Show the prompt
  deferredPrompt.prompt();
  // Wait for the user to respond to the prompt
  deferredPrompt.userChoice
    .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');
}

Safari

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

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.

Manually triggering the beforeinstallprompt event

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.

Fire the beforeinstallprompt event from DevTools:

  1. Open Chrome DevTools.
  2. Go to the Application panel.
  3. Go to the Manifest tab.
  4. Click Add to home screen, highlighted in red in the screenshot below.

Add to home screen button on DevTools