Skip to content

Installation dialog for Progressive Web Application. Provides a more convenient user experience and fixes the lack of native dialogs in some browsers.

License

Notifications You must be signed in to change notification settings

andriux1990/pwa-install

 
 

Repository files navigation

Published on NPM npm

<pwa-install>

New to PWAs? Unsure how to create a Web App? Check out these resources for a quick start: PWA Intro, PWA Starter, PWA Builder

Installation dialog for Progressive Web Application (PWA) and Add to Home Screen/Dock dialog for Web Apps. This offers an enhanced user experience and addresses the absence of native dialogs in certain browsers. 20kB brotli compressed bundle. Translation/localization is supported.

Use it as Web Component with any modern framework. No polyfill is required.

Gallery

iOS default       Install instruction App gallery       
iOS example default iOS example install instruction iOS example gallery
MacOS 14+ (Sonoma) Install instruction
sonoma_dialog-min sonoma-dialog-open-min
iPadOS
iPadOS example light
Android App gallery   Light theme  
Android example default Android example gallery Android example white
Chrome  App Gallery  
Chrome example default Chrome example gallery

Install

npm i @khmyznikov/pwa-install

Alternatively, you can use unpkg or esm.sh.

Import

import '@khmyznikov/pwa-install';

TS Config

"compilerOptions": {
  "moduleResolution": "Bundler",
  "types": ["dom-chromium-installation-events", "web-app-manifest"]
}

Use

<pwa-install></pwa-install>

React <= 18 polyfill


Supported params

<pwa-install
  manual-apple="true"
  manual-chrome="true"
  disable-chrome="true"
  disable-close="true"

  install-description="Custom call to install text"
  disable-install-description="true"
  disable-screenshots="true"
  disable-screenshots-apple="true"
  disable-screenshots-chrome="true"

  manifest-url="/manifest.json"
  name="PWA"
  description="Progressive web application"         
  icon="/icon.png">
</pwa-install>
<!-- 
  manual-apple/chrome params means you want to show the Dialog manually by showDialog().
  disable-chrome param is for completely disabling custom logic and interception for Chominum browsers (will work built-in browser logic).
--->

Make a good manifest file and don't use name/descr/icon params. Boolean attributes needs to be removed to act like "false"


Supported events

  • pwa-install-success-event
  • pwa-install-fail-event
  • pwa-install-available-event
  • pwa-user-choice-result-event
  • pwa-install-how-to-event
  • pwa-install-gallery-event
<script type="text/javascript">
  var pwaInstall = document.getElementsByTagName('pwa-install')[0];

  pwaInstall.addEventListener('pwa-install-success-event', (event) => {console.log(event.detail.message)});
</script>

⚠️ success/fail/choice events is Chromium only, iOS don't have them.


Supported properties (readonly)

  • userChoiceResult: string;
  • isDialogHidden: boolean
  • isInstallAvailable: boolean
  • isAppleMobilePlatform: boolean
  • isAppleDesktopPlatform: boolean
  • isUnderStandaloneMode: boolean
  • isRelatedAppsInstalled: boolean
<script type="text/javascript">
  var pwaInstall = document.getElementsByTagName('pwa-install')[0];

  console.log(pwaInstall.isUnderStandaloneMode);
</script>

Supported methods

  • install
  • hideDialog
  • showDialog
  • getInstalledRelatedApps: async
<script type="text/javascript">
  var pwaInstall = document.getElementsByTagName('pwa-install')[0];

  pwaInstall.install();
</script>

getInstalledRelatedApps is Chromium only, always empty on iOS.


Async mode

If you need to target Chromium browsers but you want to postpone component mounting, you can do it! But, need to capture beforeinstallprompt manually and pass it to the component's externalPromptEvent property(not attribute).

// capture event asap, better right in index.html script tag
window.addEventListener('beforeinstallprompt', (e) => {
  e.preventDefault();
  e.stopPropagation();
  e.stopImmediatePropagation();

  // save it somewhere
  window.promptEvent = e;
});

// later render the component on demand and pass event
document.getElementById("pwa-install").externalPromptEvent = window.promptEvent;

Supported localization

Translations available:

  • EN
  • RU
  • TR
  • DE
  • ES
  • NL
  • EL
  • FR
  • SR
  • PL
  • ZH/ZH-CN
  • IT
  • UK
  • CS
  • NO/NB
  • PT
  • JA
  • SV
  • KO
  • KM

Language should change automatically based on browser settings. Please create the pull-request if you want to help with translation to your language. It's an easy process.

Contribution Guidelines


ROADMAP

  • samsung mobile support
  • mozilla mobile support
  • manual theme

buy me a coffee QR PayPal QR

About

Installation dialog for Progressive Web Application. Provides a more convenient user experience and fixes the lack of native dialogs in some browsers.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • TypeScript 58.2%
  • SCSS 32.1%
  • JavaScript 9.7%