https://github.com/khmyznikov/pwa-install
Installation dialog for Progressive Web Application. Provides a more convenient user experience and fixes the lack of native dialogs in some browsers.
https://github.com/khmyznikov/pwa-install
chrome component ios lit lit-element pwa react safari typescript web-components
Last synced: 2 months ago
JSON representation
Installation dialog for Progressive Web Application. Provides a more convenient user experience and fixes the lack of native dialogs in some browsers.
- Host: GitHub
- URL: https://github.com/khmyznikov/pwa-install
- Owner: khmyznikov
- License: mit
- Created: 2020-11-08T13:49:03.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-03-27T11:59:31.000Z (3 months ago)
- Last Synced: 2025-04-04T14:12:53.477Z (3 months ago)
- Topics: chrome, component, ios, lit, lit-element, pwa, react, safari, typescript, web-components
- Language: TypeScript
- Homepage: https://khmyznikov.com/pwa-install/
- Size: 3.26 MB
- Stars: 481
- Watchers: 14
- Forks: 76
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/@khmyznikov/pwa-install)
[](https://www.npmjs.com/package/@khmyznikov/pwa-install)
## \
**New to PWAs? Unsure how to create a Web App? Check out these resources for a quick start: [PWA Intro](https://docs.pwabuilder.com/#/home/pwa-intro), [PWA Starter](https://docs.pwabuilder.com/#/starter/quick-start), [PWA Builder](https://www.pwabuilder.com/)**
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 (Safari, Firefox, Opera, etc.). **20kB brotli** compressed bundle. Translation/localization is supported.
Use it as [Web Component with any **modern** framework](https://custom-elements-everywhere.com/). No polyfill is required.
- [React <= 18 sample](https://stackblitz.com/edit/vite-react-ts-2eeiak?file=src%2FApp.tsx)
- [Angular sample](https://stackblitz.com/edit/aozf92?file=package.json,src%2Fapp%2Fpwa-install%2Fpwa-install.component.html,src%2Fapp%2Fpwa-install%2Fpwa-install.component.ts)
- [Svelte](https://stackblitz.com/edit/svelte-tab-2-sng9wa?file=src%2Froutes%2F%2Bpage.svelte)
⚡Should work with any other modern framework or just vanila js as web component.
## **[Demo](https://khmyznikov.com/pwa-install/)**
## Gallery
| iOS default | Install instruction | App gallery |
|-|-|-|
||||
| MacOS 14+ (Sonoma) | Install instruction |
|---|---|
|||
| iPadOS |
|---|
||
| Android | Firefox/Opera/Others | App gallery |
|-|-|-|
||||
| Chrome | App Gallery |
|---|---|
|||
## Install
```bash
npm i @khmyznikov/pwa-install
```
Alternatively, you can use [unpkg](https://unpkg.com) or [esm.sh](https://esm.sh).
## Import
```js
import '@khmyznikov/pwa-install';
```
## TS Config
```json
"compilerOptions": {
"moduleResolution": "Bundler",
"types": ["dom-chromium-installation-events", "web-app-manifest"]
}
```
## Use
```html
```
[React <= 18 polyfill](https://stackblitz.com/edit/vite-react-ts-2eeiak?file=src%2FApp.tsx)
### **[Demo](https://khmyznikov.com/pwa-install/)**
## Supported params
```html
```
*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
```html
var pwaInstall = document.getElementsByTagName('pwa-install')[0];
pwaInstall.addEventListener('pwa-install-success-event', (event) => {console.log(event.detail.message)});
```
*⚠️ 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
```html
var pwaInstall = document.getElementsByTagName('pwa-install')[0];
console.log(pwaInstall.isUnderStandaloneMode);
```
## Supported methods
- install
- hideDialog
- showDialog
- getInstalledRelatedApps: async
```html
var pwaInstall = document.getElementsByTagName('pwa-install')[0];
pwaInstall.install();
```
*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).
```javascript
// 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-CN*/*ZH-HK*
- *IT*
- *UK*
- *CS*
- *NO/NB*
- *PT*
- *JA*
- *SV*
- *KO*
- *KM*
- *DA*
- *VI*
- *FA*
- *HU*
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](./CONTRIBUTING.md)
## ROADMAP
- samsung mobile support
- mozilla mobile support
- manual theme
[
](https://www.buymeacoffee.com/khmyznikov)
[
](https://paypal.me/hmyznikov)
## One-time Backers ❤️
[Patrick Voigt](https://github.com/pvo13)
[Darren Debono](https://github.com/amigabits)
[Angelo Fan](https://github.com/angelofan)
[Chris Cherniakov](https://github.com/Taequn)
[Moddy](https://github.com/moddyio)
[Pavlo Hromadchuk](https://github.com/hromadchuk)
Leek Duck