Add to Home Screen

Pete is a Developer Advocate

If your PWA has use cases where it’s helpful for a user to install your app, for example if you have users who use your app more than once a week, you should be promoting the installation of your PWA within the web UI of your app.

Add to Home Screen, sometimes referred to as the web app install prompt, makes it easy for users to install your Progressive Web App on their mobile or desktop device. After the user accepts the prompt, your PWA will be added to their launcher, and it will run like any other installed app.

Chrome handles most of the heavy lifting for you:

On mobile, Chrome will generate a WebAPK, creating an even more integrated experience for your users.
On desktop, your app will installed, and run in an app window.

What are the criteria?

In order for a user to be able to install your Progressive Web App, it needs to meet the following criteria:

The web app is not already installed.
- and prefer_related_applications is not true.
Meets a user engagement heuristic (previously, the user had to interact with the domain for at least 30 seconds, this is not a requirement anymore)
Includes a web app manifest that includes:
- short_name or name
- icons must include a 192px and a 512px sized icons
- start_url
- display must be one of: fullscreen, standalone, or minimal-ui
Served over HTTPS (required for service workers)
Has registered a service worker with a fetch event handler

When these criteria are met, will fire a beforeinstallprompt event that you can use to prompt the user to install your Progressive Web App, and may show a mini-info bar. See Listen for beforeinstallprompt.

Other browsers have different criteria for installation, or to trigger the beforeinstallprompt event. Check their respective sites for full details: Edge, Firefox, Opera, Samsung Internet, and UC Browser.

Show the Add to Home Screen dialog

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

Listen for the beforeinstallprompt event
Notify the user your app can be installed with a button or other element that will generate a user gesture event.
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) => {
  // Stash the event so it can be triggered later.
  deferredPrompt = e;
  ...
});

Notify the user your app can be installed

There are many different patterns that you can use to notify the user your app can be installed and promote the installation, for example, a button in the header, an item in the navigation menu, or an item in your content feed.

window.addEventListener('beforeinstallprompt', (e) => {
  // Stash the event so it can be triggered later.
  deferredPrompt = e;
  // Update UI notify the user they can add to home screen
  showInstallPromotion();
});

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 dismisses it, you'll need to wait until the beforeinstallprompt event is fired on the next page navigation.

The mini-info bar

The mini-infobar is one technique you can use to promote the installation of your Progressive Web App on mobile. The mini-infobar will appear when the site meets the criteria, and once dismissed by the user, it will not appear again until a sufficient amount of time has passed (currently 3 months).

The mini-infobar is an interim experience for Chrome on Android as we work towards creating a consistent experience across all platforms that includes an install button into the omnibox.

Preventing the mini-infobar from appearing

Starting in Chrome 76 (July 2019), you can prevent the mini-infobar from appearing by calling preventDefault() on the beforeinstallprompt event.

window.addEventListener('beforeinstallprompt', (e) => {
  // Prevent Chrome 76 and later from showing the mini-infobar
  e.preventDefault();
  // Stash the event so it can be triggered later.
  deferredPrompt = e;
  showInstallPromotion();
});

If you decide to call preventDefault(), be sure to provide some indication to the user that your Progressive Web App is installable.

Determine if the app was successfully installed

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

window.addEventListener('appinstalled', (evt) => {
  console.log('a2hs installed');
});

Detecting if your 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

Android

On Android, when the WebAPK is launched, Chrome will check the currently installed manifest against the live manifest. If an update is required, it will be queued and updated once the device has is plugged in and connected to WiFi.

Desktop

On Desktop, the manifest is not automatically updated, but this is planned for a future update.

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

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

Chrome OS, Linux, or Windows

Open Chrome DevTools
Go to the Application panel.
Go to the Manifest tab.
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.

Feedback

Was this page helpful?

Yes

What was the best thing about this page?

It helped me complete my goal(s)