A tiny vanilla (zero-dependency) non-visual native browser web component (plug-n-play custom HTML element and extensible class) that helps implement custom patterns for promoting progressive web apps (PWA) installation.

It's compatible with Google Polymer library data binding.

Table of contents

• API
• Methods
• Properties
• Attributes
• Events
• Install
• Import
• Local
  • JS
  • HTML
  • Import maps
  • JS
  • HTML
  • Dev Servers / Builders
  • JS
  • HTML
• CDN
  • UNPKG
  • JS
  • HTML
  • ESM CDN
  • JS
  • HTML
  • Skypack
  • JS
  • HTML
• Use
• HTML
• JS
  • Use case
  • Use case
• CSS
  • Use case
• Lit
• Polymer
  • Use case
• Customize
• Further reading

API

Methods

Method	Type	Modifiers
prompt	(): ?Promise<Object>	async
getInstalledRelatedApps	(): ?Promise<Array>	async

Properties

Property	Type	Modifiers
isInstallSupported	?boolean	readonly
isInstallAvailable	?boolean	readonly
platforms	?Array	readonly
choiceResult	?Object	readonly
isGetInstalledRelatedAppsSupported	?boolean	readonly
relatedApps	?Array	readonly

Attributes

Attribute	Type	Modifiers
is-install-supported	?boolean	readonly
is-install-available	?boolean	readonly
is-get-installed-related-apps-supported	?boolean	readonly

Events

Event	Bubbles	Composed
pwa-install-available	true	true
pwa-install-installing	true	true
pwa-install-installed	true	true
pwa-install-error	true	true
is-install-supported-changed	false	false
is-install-available-changed	false	false
platforms-changed	false	false
choice-result-changed	false	false
is-get-installed-related-apps-supported-changed	false	false
related-apps-changed	false	false

Install

npm i @progressivewebcomponents/pwa-install

Import

Local

JS

import './node_modules/@progressivewebcomponents/pwa-install/pwa-install.js';

Advanced usage

See the Customize section for how to use the code below:

js import { PWAInstall } from './node_modules/@progressivewebcomponents/pwa-install/pwa-install-class.js';

HTML

<script
  type="module"
  src="https://github.com/ProgressiveWebComponents/pwa-install/raw/v0.2.2/node_modules/@progressivewebcomponents/pwa-install/pwa-install.js"
>
</script>

<script type="module">
  import './node_modules/@progressivewebcomponents/pwa-install/pwa-install.js';
</script>

Advanced usage

See the Customize section for how to use the code below:

```html

```

Import maps

<script type="importmap">
  {
    "imports": {
      "pwa-install": "./node_modules/@progressivewebcomponents/pwa-install/pwa-install.js",
      "pwa-install/": "./node_modules/@progressivewebcomponents/pwa-install/"
    }
  }
</script>

JS

import 'pwa-install';

Advanced usage

See the Customize section for how to use the code below:

js import { PWAInstall } from 'pwa-install/pwa-install-class.js';

HTML

<script type="module">
  import 'pwa-install';
</script>

Advanced usage

See the Customize section for how to use the code below:

```html

```

Dev Servers / Builders

JS

import '@progressivewebcomponents/pwa-install';

Advanced usage

See the Customize section for how to use the code below:

js import { PWAInstall } from '@progressivewebcomponents/pwa-install/pwa-install-class.js';

HTML

<script type="module">
  import '@progressivewebcomponents/pwa-install';
</script>

Advanced usage

See the Customize section for how to use the code below:

```html

```

CDN

UNPKG

JS

import 'https://unpkg.com/@progressivewebcomponents/pwa-install';

Advanced usage

See the Customize section for how to use the code below:

js import { PWAInstall } from 'https://unpkg.com/@progressivewebcomponents/pwa-install/pwa-install-class.js';

HTML

<script
  type="module"
  src="https://unpkg.com/@progressivewebcomponents/pwa-install"
>
</script>

<script type="module">
  import 'https://unpkg.com/@progressivewebcomponents/pwa-install';
</script>

Advanced usage

See the Customize section for how to use the code below:

```html

```

ESM CDN

JS

import 'https://esm.sh/@progressivewebcomponents/pwa-install';

Advanced usage

See the Customize section for how to use the code below:

js import { PWAInstall } from 'https://esm.sh/@progressivewebcomponents/pwa-install/pwa-install-class.js';

HTML

<script
  type="module"
  src="https://esm.sh/@progressivewebcomponents/pwa-install"
>
</script>

<script type="module">
  import 'https://esm.sh/@progressivewebcomponents/pwa-install';
</script>

Advanced usage

See the Customize section for how to use the code below:

```html

```

Skypack

JS

import 'https://cdn.skypack.dev/@progressivewebcomponents/pwa-install';

Advanced usage

See the Customize section for how to use the code below:

js import { PWAInstall } from 'https://cdn.skypack.dev/@progressivewebcomponents/pwa-install/pwa-install-class.js';

HTML

<script
  type="module"
  src="https://cdn.skypack.dev/@progressivewebcomponents/pwa-install"
>
</script>

<script type="module">
  import 'https://cdn.skypack.dev/@progressivewebcomponents/pwa-install';
</script>

Advanced usage

See the Customize section for how to use the code below:

```html

```

Use

HTML

<pwa-install id="a2hs"></pwa-install>

JS

const pwaInstall = document.getElementById('a2hs');

const choiseResult = await pwaInstall.prompt();

const relatedApps = await pwaInstall.getInstalledRelatedApps();

let isInstallSupportedPropertyValue = pwaInstall.isInstallSupported;

let isInstallAvailablePropertyValue = pwaInstall.isInstallAvailable;

let platformsPropertyValue = pwaInstall.platforms;

let choiceResultPropertyValue = pwaInstall.choiceResult;

let isGetInstalledRelatedAppsSupportedPropertyValue = pwaInstall.isGetInstalledRelatedAppsSupported;

let relatedAppsPropertyValue = pwaInstall.relatedApps;

let isInstallSupportedAttributeValue = pwaInstall.hasAttribute('is-install-supported');

let isInstallAvailableAttributeValue = pwaInstall.hasAttribute('is-install-available');

let isGetInstalledRelatedAppsSupportedAttributeValue = pwaInstall.hasAttribute('is-get-installed-related-apps-supported');

pwaInstall.addEventListener('pwa-install-available', handlePWAInstallAvailableEvent);

pwaInstall.addEventListener('pwa-install-installing', handlePWAInstallInstallingEvent);

pwaInstall.addEventListener('pwa-install-installed', handlePWAInstallInstalledEvent);

pwaInstall.addEventListener('pwa-install-error', handlePWAInstallErrorEvent);

const handlePWAInstallAvailableEvent = (event) => {
  // Use event.detail.value and/or run any code
}

const handlePWAInstallInstallingEvent = (event) => {
  // Use event.detail.value and/or run any code
}

const handlePWAInstallInstalledEvent = (event) => {
  // Use event.detail.value and/or run any code
}

const handlePWAInstallErrorEvent = (event) => {
  // Use event.detail.message.error, event.detail.value and/or run any code
}

Use case

Events can be used to collect telemetry on (promoting) PWA installation and send it to e.g. Google Analytics:

const handlePWAInstallAvailableEvent = (event) => {
  window.gtag?.('event', 'pwa-install', {
    'state': 'available',
    'platforms': event.detail.value,
  });
}

const handlePWAInstallInstallingEvent = (event) => {
  window.gtag?.('event', 'pwa-install', {
    'state': 'installing',
    'outcome': event.detail.value?.outcome,
    'platform': event.detail.value?.platform,
  });
}

const handlePWAInstallInstalledEvent = (event) => {
  window.gtag?.('event', 'pwa-install', {
    'state': 'installed',
    'platform': event.detail.value?.platform,
  });
}

const handlePWAInstallErrorEvent = (event) => {
  window.gtag?.('event', 'pwa-install', {
    'state': 'error',
    'error': event.detail.message.error,
    'platform': event.detail.value?.platform,
  });
}

pwaInstall.addEventListener('is-install-supported-changed', handleIsInstallSupportedPropertyChangedEvent);

pwaInstall.addEventListener('is-install-available-changed', handleIsInstallAvailablePropertyChangedEvent);

pwaInstall.addEventListener('platforms-changed', handlePlatformsPropertyChangedEvent);

pwaInstall.addEventListener('choice-result-changed', handleChoiceResultPropertyChangedEvent);

pwaInstall.addEventListener('is-get-installed-related-apps-supported-changed', handleIsGetInstalledRelatedAppsSupportedPropertyChangedEvent);

pwaInstall.addEventListener('related-apps-changed', handleRelatedAppsPropertyChangedEvent);

const handleIsInstallSupportedPropertyChangedEvent = (event) => {
  // Use event.detail.value and/or run any code
}

const handleIsInstallAvailablePropertyChangedEvent = (event) => {
  // Use event.detail.value and/or run any code
}

const handlePlatformsPropertyChangedEvent = (event) => {
  // Use event.detail.value and/or run any code
}

const handleChoiceResultPropertyChangedEvent = (event) => {
  // Use event.detail.value and/or run any code
}

const handleIsGetInstalledRelatedAppsSupportedPropertyChangedEvent = (event) => {
  // Use event.detail.value and/or run any code
}

const handleRelatedAppsPropertyChangedEvent = (event) => {
  // Use event.detail.value and/or run any code
}

Use case

Events can be used to update the property values:

const handleIsInstallSupportedPropertyChangedEvent = (event) => {
  isInstallSupportedPropertyValue = event.detail.value;
}

const handleIsInstallAvailablePropertyChangedEvent = (event) => {
  isInstallAvailablePropertyValue = event.detail.value;
}

const handlePlatformsPropertyChangedEvent = (event) => {
  platformsPropertyValue = event.detail.value;
}

const handleChoiceResultPropertyChangedEvent = (event) => {
  choiceResultPropertyValue = event.detail.value;
}

const handleIsGetInstalledRelatedAppsSupportedPropertyChangedEvent = (event) => {
  isGetInstalledRelatedAppsSupportedPropertyValue = event.detail.value;
}

const handleRelatedAppsPropertyChangedEvent = (event) => {
  relatedAppsPropertyValue = event.detail.value;
}

CSS

#a2hs[is-install-supported]

#a2hs[is-install-available]

#a2hs[is-get-installed-related-apps-supported]

Use ca