Add to Home Screen

The ability to add a web application to a device's home screen is a feature The Web Almanac didn't look at in last 2021's Capabilities report. To calculate how many sites have this functionality, pages were tested to see if they had a listener for the beforeinstallprompt event.

Note that the beforeinstallprompt event is a Chromium-only API and is currently incubating within the WICG.

The beforeinstallprompt event triggers right before a user is about to be prompted to "install" a web app. The usage of an event listener for the beforeinstallprompt event is not required for web apps to be added to a device's home screen, so it is safe to assume that the actual usage is much higher. However, this methodology will allow us to get an idea of how popular of a feature it is.

The ability to add an application to the home screen is a crucial feature of PWAs. To use this feature, web applications must meet the following criteria:

The web app must not already be installed.
The user must have spent at least 30 seconds viewing the page at any time.
The user must have clicked or tapped at least once on the page at any time.
The web app must be served over HTTPS.
The web app must include a web app manifest with:
- short_name or name.
- icons (must include a 192x192px and a 512x512px icon).
- start_url.
- display (must be one of fullscreen, standalone, or minimal-ui).
- prefer_related_applications (must not be present, or be false).
The web app must register a service worker with a fetch handler.

Installed applications can appear in Start menus, desktops, home screens, the Applications folder, when searching for applications on a device, content sharing sheets, and more.

The ability to add to the home screen is only available on modern versions of Chrome, Edge, and Safari on iOS and iPadOS.

Add to Home Screem Example

import { useEffect, useState } from "react";

export default function AddToHomeScreenButton() {
  const [installPrompt, setInstallPrompt] = useState<any>();

  useEffect(() => {
    const installHandler = (event: Event) => {
      event.preventDefault();
      setInstallPrompt(event);
    };

    window.addEventListener("beforeinstallprompt", installHandler);

    return () =>
      window.removeEventListener("beforeinstallprompt", installHandler);
  });

  const onClick = async () => {
    if (!installPrompt) return;
    await installPrompt.prompt();
    setInstallPrompt(false);
  };

  return (
    <button onClick={onClick} disabled={!installPrompt}>
      Install this Demo!
    </button>
  );
}

Usage

As mentioned, the add to home screen capability was not measured last year. However, for posterity and detailed reporting, the beforeinstallprompt event was used on 8.56% of desktop pages and 7.71% of mobile pages, making it the third most used capability on desktop and mobile.

By taking advantage of the beforeinstallprompt event, developers can provide a customized experience in how users install their web application. One example is YouTube TV, which invites users to install their application to access it more quickly and easily.

Installing YouTube TV from an in app prompt, powered by the beforeinstallprompt event. — Figure 1. Installing YouTube TV from an in app prompt, powered by the `beforeinstallprompt` event.