Making PWAs installable

One of the defining aspects of a PWA is that it can be installed on the device, and then appears to users as a platform-specific app, a permanent feature of their device which they can launch directly from the operating system like any other app.

We can summarize this as follows:

  • The PWA can be installed from the platform's app store or installed directly from the web.
  • The PWA can be installed like a platform-specific app, and can customize the install process.
  • Once installed, the PWA gets an app icon on the device, alongside platform-specific apps.
  • Once installed, the PWA can be launched as a standalone app, rather than a website in a browser.

We'll discuss each of these features in this guide. First, though, we'll discuss the requirements that a web app must meet for it to be installable.

Installability

For a web app to be installable, it needs to meet some technical requirements. We can consider these the minimum requirements for a web app to be a PWA.

The web app manifest

A web app manifest is a JSON file that tells the browser how the PWA should appear and behave on the device. For a web app to be a PWA it must be installable, and for it to be installable it must include a manifest.

The manifest is included using a <link> element in the app's HTML:

html

<!DOCTYPE html>
<html lang="en">
  <head>
    <link rel="manifest" href="manifest.json" />
    <!-- ... -->
  </head>
  <body></body>
</html>

If the PWA has more than one page, every page must reference the manifest in this way.

The manifest contains a single JSON object containing a collection of members, each of which defines some aspect of the PWA's appearance or behavior. Here's a rather minimal manifest, containing just two members: "name" and "icons".

json

{
  "name": "My PWA",
  "icons": [
    {
      "src": "icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
    }
  ]
}

Required manifest members

Chromium-based browsers, including Google Chrome, Samsung Internet, and Microsoft Edge, require that the manifest includes the following members:

For a full description of every member, see the web app manifest reference documentation.

HTTPS

For a web app to be installable, it must be served over HTTPS.

Note that to make development easier, browsers do not require HTTPS if the web app is accessed via the localhost domain.

Service worker

For a web app to be installable, it must include a service worker with a fetch event handler that provides a basic offline experience.

Installation from an app store

Users expect to find apps in the app store for their platform, like the Google Play Store or the Apple Store.

If your app meets the installability prerequisites, you can package it and distribute it through app stores. The process is specific to each app store:

The PWABuilder is a tool to simplify the process of packaging and publishing a PWA for various app stores. It supports the Google Play Store, Microsoft Store, Meta Quest Store, and iOS App Store.

If you have added your app to the app store, users can install it from there, just like a platform-specific app.

Installation from the web

When the user visits a web page that the browser has determined is installable, then the user will be offered the chance to install it. This means you can distribute your PWA as a website, making it discoverable through web search, and also distribute it in app stores, so users can find it there.

This is a great example of the way PWAs can offer you the best of both worlds. It's also a good example of how progressive enhancement works with PWAs: if a user encounters your PWA on the web, using a browser that can't install it, they can use it just like a normal website.

The UI for installing a PWA from the web varies from one browser to another, and from one platform to another. For example, a browser might include an "Install" icon in the URL bar when the user navigates to the page:

Chrome URL bar, showing PWA install icon

When the user selects the icon, the browser displays a prompt asking if they want to install the PWA, and if they accept, the PWA is installed.

The prompt displays the name and icon for the PWA, taken from the name and icons manifest members.

Browser support

Support for installing PWAs from the web varies by browser and by platform.

On desktop:

  • Firefox and Safari do not support installing PWAs on any desktop operating systems.
  • Chrome and Edge support installing PWAs on Linux, Windows, macOS, and Chromebooks.

On mobile:

  • Firefox, Chrome, Edge, Opera, and Samsung Internet Browser all support installing PWAs on Android.
  • Only Safari is allowed to install PWAs on iOS.

Triggering the install prompt

A PWA can provide its own in-page UI for the user to open the install prompt, instead of relying on the UI provided by the browser by default. This enables a PWA to provide some context and a reason for the user to install the PWA, and can help make the install user flow easier to discover.

This technique relies on the beforeinstallprompt event, which is fired on the global Window object as soon as the browser has determined that the PWA is installable. This event has a prompt() method that shows the install prompt. So a PWA can:

  • add its own "Install" button
  • listen for the beforeinstallprompt event
  • cancel the event's default behavior by calling preventDefault()
  • in the event handler for its own "Install" button, call prompt().

Customizing the installation prompt

By default, the install prompt contains the name and icon for the PWA. If you provide values for the description and screenshots manifest members, then, on Android only, these values will be shown in the install prompt, giving the user extra context and motivation to install the PWA.

The screenshot below shows what the install prompt for the PWAmp demo looks like on Google Chrome, running on Android:

Install prompt for PWAmp on Android

Launching the app

Once the PWA is installed, its icon is shown on the device alongside any other apps that the user has installed, and clicking the icon launches the app.

You can use the display manifest member to control the display mode: that is, how the PWA appears when it is launched. In particular:

  • "standalone" indicates that the PWA should look and feel like a platform-specific application, with no browser UI elements
  • "browser" indicates that the PWA should be opened as a new browser tab or window, just like a normal website.

If the browser does not support a given display mode, display will fall back to a supported display mode according to a predefined sequence. The display_override enables you to redefine the fallback sequence.