add-to-homescreen-react v1.0.0

add-to-homescreen-react

A React component providing add-to-home-screen functionality for different platforms and browsers.

What is it?

add-to-homescreen-react allows you to easily inform your user that your React application is installable on the home screen of your mobile phone or on your desktop. It provides a highly configurable React component named AddToHomeScreen that supports different browsers and platforms. Where possible, browser's native add-to-homescreen functionality is used. Where not, a guidance for the user can be shown.

This library is based on the add-to-homescreen project of Chris Love.

Usage

First import the component:

import AddToHomeScreen from 'add-to-homescreen-react';

Then add the component to your app:

<AddToHomeScreen />

This is the simplest way to use this component. There is a wide range of configuration options available you can use to customize the behaviour and design of the component. See section Configuration for the Add-to-home-screen module for a description of all available configuration parameters.

Configuration for the Add-to-home-screen module

Configuration is defined in the addToHomeScreenConfiguration.json file. The following parameters exist and can be customized:

Custom Prompt Content

The customPromptContent configuration parameter allows to globally define (for all platforms) the content of the custom prompt dialog. It contains the following customizable parameters:

Please note that the messages can be defined per platform too. See section Browser specific prompt dialog configuration to learn how.

Browser specific prompt dialog configuration

Some platforms support a native add-to-home-screen dialog, others not. For the second ones the add-to-home-screen custom dialog shows a guide (one or more images) that illustrates how the app can be added to the home screen. The customPromptPlatformDependencies parameter allows to customize this guide. It contains a configuration entry for each of the supported platforms. The following platforms are supported:

The configuration entries for each platform contain the following customizable parameters:

An image definition consists of the following configuration parameters:

The action message definition consists of the following configuration parameters:

Here is an example for a complete platform entry:

"iphone": {
  targetUrl: undefined,
  showClasses: ["iphone-wrapper", "animated", "fadeIn", "d-block"],
  images: [
    {
      src: "/images/addToHomeScreen/iphone.png",
      alt: "Tap the Share Icon and select Add to home screen entry"
    }
  ],
  action: {
    ok: "Ok",
    cancel: "Cancel",
    guidanceCancel: "Dismiss"
  }
}

Customizing add-to-homescreen prompt

Per default, the AddToHomeScreen component brings a default styling based on a predefined set of CSS classes. You can change this styling by defining your own CSS rules for these classes. If you need more changes or want a complete redesign of the custom prompt dialog, it may be helpful to define a complete new CSS rule set based on your own CSS classes. The customPromptElements configuration parameter allows you to define CSS classes for all HTML elements of the add-to-homescreen custom prompt. It consists of a set of configuration parameters defining these classes. For a better understanding of these parameters, here is the HTML structure of the custom prompt dialog:

<div class="{container}">
    <div class="{banner}">
      <div class="{logoCell}>
        <img class="{logo}"/>
      </div>
      <div class="{titleCell}">
        <div class="{title}"/>
      </div>
      <div class="{cancelButtonCell}">
        <button class="{cancelButton}"/>
      </div>
      <div class="{installButtonCell}">
        <button class="{installButton}"/>
      </div>
    </div>
    <div class="{guidance}">
      <div class="{guidanceImageCell}"/>
      <div class="{cancelButtonCell}">
        <button class="{guidanceCancelButton}"/>
      </div>
    </div>
</div>

The values in brackets ({}) are the configuration keys you can use within the customPromptElements parameter to define or change the CSS classes. The following table describes these keys and their default value.

Please note, that each of these keys accepts only one CSS class. This is necessary to enable the AddToHomeScreen component to use this CSS class as accessor to the corresponding HTML element. For your CSS ruleset you can add further CSS classes to the elements by the corresponding AddOns-keys that exist for each of the CSS class key in the table above. Here is an overview of these AddOns-Keys and their default values:

There is another configuration key named showClasses that can be used to define CSS classes that are added dynamically to the prompt dialog wrapper (the container) whenever it is shown. This can be done globally (see section Configuration for the Add-to-home-screen module) or per supported browser or platform (see section Browser specific prompt dialog configuration).

Licence

Copyright (c) 2014 Matteo Spinelli, http://cubiq.org/

Copyright (c) 2019 Chris Love, http://love2dev.com/

Copyright (c) 2019 Axel Springer Ideas Engineering GmbH, https://ideas-engineering.io/

This software is subject to the provisions of LPGLv3.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.