{"id":14990135,"url":"https://github.com/khmyznikov/pwa-install","last_synced_at":"2025-04-11T19:45:25.541Z","repository":{"id":38839354,"uuid":"311073027","full_name":"khmyznikov/pwa-install","owner":"khmyznikov","description":"Installation dialog for Progressive Web Application. Provides a more convenient user experience and fixes the lack of native dialogs in some browsers.","archived":false,"fork":false,"pushed_at":"2025-03-27T11:59:31.000Z","size":3418,"stargazers_count":481,"open_issues_count":10,"forks_count":76,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-04-04T14:12:53.477Z","etag":null,"topics":["chrome","component","ios","lit","lit-element","pwa","react","safari","typescript","web-components"],"latest_commit_sha":null,"homepage":"https://khmyznikov.com/pwa-install/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/khmyznikov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["khmyznikov"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":"khmyznikov","custom":["https://paypal.me/hmyznikov"]}},"created_at":"2020-11-08T13:49:03.000Z","updated_at":"2025-04-04T07:09:37.000Z","dependencies_parsed_at":"2023-02-12T18:45:42.411Z","dependency_job_id":"a9759777-f0ac-454d-a709-9608ce5ee393","html_url":"https://github.com/khmyznikov/pwa-install","commit_stats":{"total_commits":293,"total_committers":28,"mean_commits":"10.464285714285714","dds":"0.20136518771331058","last_synced_commit":"5adce6e9fe417bd68c8c457201be7f69bf5ff81a"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khmyznikov%2Fpwa-install","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khmyznikov%2Fpwa-install/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khmyznikov%2Fpwa-install/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khmyznikov%2Fpwa-install/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/khmyznikov","download_url":"https://codeload.github.com/khmyznikov/pwa-install/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248469125,"owners_count":21108962,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chrome","component","ios","lit","lit-element","pwa","react","safari","typescript","web-components"],"created_at":"2024-09-24T14:19:33.759Z","updated_at":"2025-04-11T19:45:25.506Z","avatar_url":"https://github.com/khmyznikov.png","language":"TypeScript","funding_links":["https://github.com/sponsors/khmyznikov","https://buymeacoffee.com/khmyznikov","https://paypal.me/hmyznikov","https://www.buymeacoffee.com/khmyznikov"],"categories":[],"sub_categories":[],"readme":"[![Published on NPM](https://img.shields.io/npm/v/@khmyznikov/pwa-install.svg)](https://www.npmjs.com/package/@khmyznikov/pwa-install)\n[![npm](https://img.shields.io/npm/dt/@khmyznikov/pwa-install)](https://www.npmjs.com/package/@khmyznikov/pwa-install)\n## \\\u003cpwa-install\\\u003e\n\n**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/)**\n\nInstallation 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.\n\nUse it as [Web Component with any **modern** framework](https://custom-elements-everywhere.com/). No polyfill is required.\n- [React \u003c= 18 sample](https://stackblitz.com/edit/vite-react-ts-2eeiak?file=src%2FApp.tsx)\n- [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)\n- [Svelte](https://stackblitz.com/edit/svelte-tab-2-sng9wa?file=src%2Froutes%2F%2Bpage.svelte)\n  \n⚡Should work with any other modern framework or just vanila js as web component.\n\n## **[Demo](https://khmyznikov.com/pwa-install/)**\n\n## Gallery\n| iOS default\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; | Install instruction | App gallery\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; |\n|-|-|-|\n|![iOS example default](https://user-images.githubusercontent.com/6115884/169653932-5a9916b6-8d1f-4320-a595-86c3b797ae86.jpg)|![iOS example install instruction](https://user-images.githubusercontent.com/6115884/169654013-7d144d66-0021-44d8-8f1d-9a7d2c71cb07.jpg)|![iOS example gallery](https://user-images.githubusercontent.com/6115884/169654077-f48c9b63-2b6e-4291-a0e3-b33daf86d468.jpg)|\n\n| MacOS 14+ (Sonoma) | Install instruction |\n|---|---|\n|![sonoma_dialog-min](https://github.com/khmyznikov/pwa-install/assets/6115884/4ee02327-9abd-4d5e-a581-537dccb2187f)|![sonoma-dialog-open-min](https://github.com/khmyznikov/pwa-install/assets/6115884/6b147938-b55b-479a-85ea-1778868e6ff5)|\n\n\n\n| iPadOS |\n|---|\n|![iPadOS example light](https://user-images.githubusercontent.com/6115884/169654199-1b474920-089c-44b5-8eca-534229ce0720.jpg)|\n\n\n| Android | Firefox/Opera/Others | App gallery\u0026nbsp;\u0026nbsp; |\n|-|-|-|\n|![Android example default](https://user-images.githubusercontent.com/6115884/169654789-41fb88b3-97b2-4992-aab5-0def6015be21.jpg)|![Firefox Opera and others](https://github.com/user-attachments/assets/03131c42-8cd0-4e93-a2fe-d75a75223550)|![Android example white](https://user-images.githubusercontent.com/6115884/169654871-33f30d44-b70c-4912-a678-3d97fd0d80a8.jpg)|\n\n| Chrome\u0026nbsp; | App Gallery\u0026nbsp;\u0026nbsp; |\n|---|---|\n|![Chrome example default](https://user-images.githubusercontent.com/6115884/169655166-07f02a6b-a72a-4eb8-8ae1-e5a32fcac530.jpg)|![Chrome example gallery](https://user-images.githubusercontent.com/6115884/169655205-34b9b1a8-328b-45f8-8cd2-f6524e82469e.jpg)|\n\n\u003cbr\u003e\n\n## Install\n\n```bash\nnpm i @khmyznikov/pwa-install\n```\n\nAlternatively, you can use [unpkg](https://unpkg.com) or [esm.sh](https://esm.sh).\n\n\n## Import\n\n```js\nimport '@khmyznikov/pwa-install';\n```\n\n## TS Config\n```json\n\"compilerOptions\": {\n  \"moduleResolution\": \"Bundler\",\n  \"types\": [\"dom-chromium-installation-events\", \"web-app-manifest\"]\n}\n```\n\n## Use\n\n```html\n\u003cpwa-install\u003e\u003c/pwa-install\u003e\n```\n[React \u003c= 18 polyfill](https://stackblitz.com/edit/vite-react-ts-2eeiak?file=src%2FApp.tsx)\n\n### **[Demo](https://khmyznikov.com/pwa-install/)**\n\n\u003cbr\u003e\n\n## Supported params\n```html\n\u003cpwa-install\n  manual-apple=\"true\"\n  manual-chrome=\"true\"\n  disable-chrome=\"true\"\n  disable-close=\"true\"\n  use-local-storage=\"true\"\n\n  install-description=\"Custom call to install text\"\n  disable-install-description=\"true\"\n  disable-screenshots=\"true\"\n  disable-screenshots-apple=\"true\"\n  disable-screenshots-chrome=\"true\"\n\n  disable-android-fallback=\"true\"\n\n  manifest-url=\"/manifest.json\"\n  name=\"PWA\"\n  description=\"Progressive web application\"         \n  icon=\"/icon.png\"\u003e\n\u003c/pwa-install\u003e\n\u003c!-- \n  manual-apple/chrome params means you want to show the Dialog manually by showDialog().\n  disable-chrome param is for completely disabling custom logic and interception for Chromium browsers (will work built-in browser logic).\n  use-local-storage will store the user's preference to ignore the prompt in long-lived storage (so they will not be prompted again unless they clear application data)\n  disable-android-fallback will disable instructions for non-Chrome browsers on Android\n---\u003e\n```\n*Make a good manifest file and don't use name/descr/icon params. Boolean attributes needs to be removed to act like \"false\"*\n\n\u003cbr\u003e\n\n## Supported events\n- pwa-install-success-event\n- pwa-install-fail-event\n- pwa-install-available-event\n- pwa-user-choice-result-event\n- pwa-install-how-to-event\n- pwa-install-gallery-event\n\n```html\n\u003cscript type=\"text/javascript\"\u003e\n  var pwaInstall = document.getElementsByTagName('pwa-install')[0];\n\n  pwaInstall.addEventListener('pwa-install-success-event', (event) =\u003e {console.log(event.detail.message)});\n\u003c/script\u003e\n```\n*⚠️ success/fail/choice events is Chromium only, iOS don't have them.*\n\n\u003cbr\u003e\n\n## Supported properties (readonly)\n- userChoiceResult: string;\n- isDialogHidden: boolean\n- isInstallAvailable: boolean\n- isAppleMobilePlatform: boolean\n- isAppleDesktopPlatform: boolean\n- isUnderStandaloneMode: boolean\n- isRelatedAppsInstalled: boolean\n\n```html\n\u003cscript type=\"text/javascript\"\u003e\n  var pwaInstall = document.getElementsByTagName('pwa-install')[0];\n\n  console.log(pwaInstall.isUnderStandaloneMode);\n\u003c/script\u003e\n```\n\u003cbr\u003e\n\n## Supported methods\n- install\n- hideDialog\n- showDialog\n- getInstalledRelatedApps: async\n\n```html\n\u003cscript type=\"text/javascript\"\u003e\n  var pwaInstall = document.getElementsByTagName('pwa-install')[0];\n\n  pwaInstall.install();\n\u003c/script\u003e\n```\n\n*getInstalledRelatedApps is Chromium only, always empty on iOS.*\n\n\u003cbr\u003e\n\n## Async mode\n\nIf you need to target Chromium browsers but you want to postpone component mounting, you can do it!\nBut, need to capture *beforeinstallprompt* manually and pass it to the component's *externalPromptEvent* property(not attribute).\n\n```javascript\n// capture event asap, better right in index.html script tag\nwindow.addEventListener('beforeinstallprompt', (e) =\u003e {\n  e.preventDefault();\n  e.stopPropagation();\n  e.stopImmediatePropagation();\n\n  // save it somewhere\n  window.promptEvent = e;\n});\n\n// later render the component on demand and pass event\ndocument.getElementById(\"pwa-install\").externalPromptEvent = window.promptEvent;\n```\n\u003cbr\u003e\n\n## Supported localization\n\nTranslations available:\n- *EN*\n- *RU*\n- *TR*\n- *DE*\n- *ES*\n- *NL*\n- *EL*\n- *FR*\n- *SR*\n- *PL*\n- *ZH-CN*/*ZH-HK*\n- *IT*\n- *UK*\n- *CS*\n- *NO/NB*\n- *PT*\n- *JA*\n- *SV*\n- *KO*\n- *KM*\n- *DA*\n- *VI*\n- *FA*\n- *HU*\n\nLanguage 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.\n\n[Contribution Guidelines](./CONTRIBUTING.md)\n\n\u003cbr\u003e\n\n## ROADMAP\n- samsung mobile support\n- mozilla mobile support\n- manual theme\n\n\n[\u003cimg alt=\"buy me a coffee QR\" src=\"https://github.com/khmyznikov/pwa-install/assets/6115884/5168f0db-2317-4ec2-8362-d828ffa2a8bf\" width=\"200\"\u003e](https://www.buymeacoffee.com/khmyznikov)\n[\u003cimg alt=\"PayPal QR\" src=\"https://github.com/khmyznikov/pwa-install/assets/6115884/6290b136-d525-4f8e-95fe-4729ea4c6414\" width=\"200\"\u003e](https://paypal.me/hmyznikov)\n\n## One-time Backers ❤️\n[Patrick Voigt](https://github.com/pvo13)\u003cbr\u003e\n[Darren Debono](https://github.com/amigabits)\u003cbr\u003e\n[Angelo Fan](https://github.com/angelofan)\u003cbr\u003e\n[Chris Cherniakov](https://github.com/Taequn)\u003cbr\u003e\n[Moddy](https://github.com/moddyio)\u003cbr\u003e\n[Pavlo Hromadchuk](https://github.com/hromadchuk)\u003cbr\u003e\nLeek Duck\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhmyznikov%2Fpwa-install","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkhmyznikov%2Fpwa-install","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhmyznikov%2Fpwa-install/lists"}