react-pwa-install

Install handling for your React PWA.

The problem this package is trying to solve

Since intalling a PWA (aka Add to home screen) is handled differently by different browsers, it's rather hard to give this option to users conveniently. Currently only Chrome, Edge and Samsung Internet support this feature natively using the BeforeInstallPromptEvent. On iOS devices, FireFox mobile or Opera mobile the user needs to perform some manual steps to install the app to the home screen. Very few know this option even exists.

What this package does

This package provides a simple way to add a custom PWA installing capability to your app on several platforms, while not trying to do too much in terms of when and how or how often the install prompt is shown to the user. This is application dependent and should be left for the app developer to define.

If a user is visiting your PWA from a browser that supports the native BeforeInstallPromptEvent, then this method will be used for the installation. ( Currently: Chrome - mobile and desktop, Edge - mobile, Samsung internet )
If a user is visiting your PWA from a browser that supports "manual installation", then instructions will be shown to them. ( Currently iOS devices, FireFox - mobile, Opera - mobile).

Demo

To view the demo visit: https://zoltangy.github.io/react-pwa-install-demo/ (view source code).

Installation

To use the package, you also need to install @material-ui/core.

$ npm i --save react-pwa-install @material-ui/core

Prerequisites

Make sure that your PWA is installable. You can use Lighthouse from Chrome DevTools to run a PWA Audit.

Please also read this guide on best practices to promote the installation of your app.

Usage

Import ReactPWAInstallProvider and useReactPWAInstall
Wrap your App with the ReactPWAInstallProvider.
Use the supported and isInstalled (desctructed from useReactPWAInstall) functions to determine whether to show your Install button (or banner,popup,etc...). Generally, the install button should only be shown if supported returns true and isInstalled returns false. (You should add the app specific criterias on top of this: amount of time spent on the site, certain engagement, etc.)
Call pwaInstall (desctructed from useReactPWAInstall) when the user clicked on the install button. See the list of options below. You might want to handle rejection (or possible rejection) here, and not prompt the user again for a certain period of time or until a new meaningful engagement.

import React from "react";
import ReactDOM from "react-dom";
import ReactPWAInstallProvider, { useReactPWAInstall } from "react-pwa-install";
import myLogo from "img/logo.png";

function App() {
  const { pwaInstall, supported, isInstalled } = useReactPWAInstall();

  const handleClick = () => {
    pwaInstall({
      title: "Install Web App",
      logo: myLogo,
      features: (
        <ul>
          <li>Cool feature 1</li>
          <li>Cool feature 2</li>
          <li>Even cooler feature</li>
          <li>Works offline</li>
        </ul>
      ),
      description: "This is a very good app that does a lot of useful stuff. ",
    })
      .then(() => alert("App installed successfully or instructions for install shown"))
      .catch(() => alert("User opted out from installing"));
  };

  return (
    <div>
      {supported() && !isInstalled() && (
        <button type="button" onClick={handleClick}>
          Install App
        </button>
      )}
    </div>
  );
}

ReactDOM.render(
  <ReactPWAInstallProvider enableLogging>
    <App />
  </ReactPWAInstallProvider>,
  document.querySelector("#root")
);

API

ReactPWAInstallProvider: Context provider, required. For debug purposes, the enableLogging property can be used.
useReactPWAInstall: React hook that provides pwaInstall, supported, isInstalled
supported: Helper function to decide if the install button should be shown to the user. Returns true in 2 cases:
- the beforeinstallprompt event is supported, and it has fired
- manual installation is supported
isInstalled: Helper function to decide if the install button should be shown to the user. Returns true if the user is currently visiting the site from the installed 'standalone' app.
pwaInstall: Will open the installation dialog according to the user's platform. See below for options. This function returns a promise. The promise is rejected only if the user cancels the native installation process. The promise is fulfilled when the native installation was successful or when the manual installation steps were shown.

Options for `pwaInstall`

The following options are available to customize the install dialog:

Prop	type	Default Value	Description
`title (optional)`	string	Install Web App	The header of the dialog window
`logo (optional)`	string	-	Path to an image representing the app, typically the icon
`features (optional)`	React.ReactNode	-	A list of features, see "Usage" for an example
`description (optional)`	string	-	Description of the app

Customization

To customize the colors and fonts of the dialog, you can wrap the ReactPWAInstallProvider with a Material-UI ThemeProvider. See https://material-ui.com/customization/theming/ for more info.

jono-allen/react-pwa-install