Installing Progressive Web Apps

Justin Willis
Nov 5 · 6 min read

Historically the PWABuilder team has been focused on helping developers with the basics of creating a Progressive Web App. When the PWABuilder project started, tooling for PWAs was still very early and most web frameworks did not give you a PWA by default. Luckily, today that story is very different and all the major web frameworks (React, Vue, Angular etc) now give you a PWA out of the box. What this also means thought is that its time to change our focus for PWABuilder from purely helping developers get started with PWAs to our new goal, helping developers build great PWAs that provide an awesome user experience! We want to help developers fill in the gaps that separate PWAs from native app experiences, and today we are announcing our first project with this new goal in mind!

The one thing that has always separated the web from native is that a native app can be installed by the user, leading to higher engagement with users, while web apps were stuck in the browser. PWAs opened the possibility for web apps to be installed by the user, but we have always been reliant on what the browser provides as an install experience which we have found lacking.

Today, the PWABuilder team is releasing a new Web Component called pwa-install! The pwa-install component takes the standard PWA browser install experience further by using web APIs available in modern browsers to deliver a more app store like install experience for users! Lets dive a little deeper into installing PWAs to understand the challenges this component aims to solve, and then ill show how the component works!

live demo

Installing PWAs

Before we dive into how this component works, I want to cover the existing in-browser install experience.


On the mobile side of things, Chrome, Chromium based browsers like Microsoft Edge and Samsung Internet, and Firefox for Android all currently support a basic browser install experience. Let’s look at what this mobile install experience looks like:

As you can see from the above screenshot, when Edge detects that I am using a PWA it will pop up an install banner from the bottom of the screen. If you click that banner Edge will then install the PWA to your device. This is much better than we have ever had on the web and does get the job done, but it is not ideal.

First, this banner does not give the user any more info about the app they are questioned to add to their homescreen. Users are accustomed to seeing descriptions, screenshots, key features and more about an app when they are installing it, which leads to my last point.

Users, especially on mobile, have traditionally gotten all their apps from an app store like Google Play. Because of this, users have come to expect things like an app store experience when they are installing apps, and the current install banner for PWAs does not fill this gap.


On desktop we face the same challenges, but I wanted to touch on some UI differences in the desktop version of the install banner we saw on mobile:

On desktop the install banner takes the shape of an install button in the URL bar of the browser. When the user clicks this, they are greeted with a small dropdown that shows the icon of the PWA along with install and cancel buttons.

To review, the main challenge associated today with the install experience for PWAs is a lack of info for the user which then leads to confusion. We’ve even shown this current experience to dev teams and the first comment was wait, what just happened. Luckily though, modern browsers give us some APIs that allow us to tie into this install experience in a basic way, which means we can build a better install experience ourselves!

@pwabuilder/pwainstall 👏👏

The PWABuilder team has been hard at work over the past few weeks and we are excited to announce the <pwa-install /> component! Inspired by our friends over at the Microsoft Graph Toolkit this is a web component built with lit-element. Because this is a web component that means it will work with all your favorite frameworks right out of the box while also being tiny enough that it does not impact your loading performance, the best of both worlds!

The pwa-install component tries to solve the challenges in the install experience we talked about above while also serving as an example of what the browser supplied install experience could look like. This component reads your web manifest and uses that info to display an app store like install screen to the user when they hit an install button:

Oh and did I mention it only takes 2 lines of HTML to use it?

Code for using the pwa-install component

The pwa-install component can also be install from NPM with npm install @pwabuilder/pwainstall

These 2 lines of html take care of loading the component, showing an install button when appropriate and finally, displaying the install screen:

GIF of the component working on Desktop
The pwa-install component running on a mobile device

As mentioned above, this component reads your web manifest to know what info to display about your app. We currently use the description, screenshots, theme_color, short_name, name and icons entries to provide all of the info you see in the above screenshot, but these are not required for the component to work which allows you to update your manifest over time with these missing entries.

Before moving on I also wanted to touch on best practices for using this component. To ensure the best user experience for your app, we recommend only displaying this component in a way that is not too distracting for the user. In my PWAs, I have found that the best way to do this is to show the install button is in a header or footer, and possibly only after the user has interacted with the app. This shows the install button for the user, but ensures that the experience of the app is not blocked by the install and that the user is not being spammed with install requests for something they have barely used. As developers of PWAs, we have to remember that not everyone who comes to our PWA in the browser is going to install it the first time, therefore installing should not be a core part of your experience.

Finally, if you are looking for a quick way to generate a quality web manifest, you can use PWABuilder or the PWABuilder VSCode extension. PWABuilder will load your PWA and guide you in creating an awesome web manifest.

Open Source

As with most things we do on the PWABuilder team, this component is completely open source and the source code is available on GitHub. If you have ideas on how to make this component better or are just looking for an inclusive open source community to be a member of, we would love for you to help us build out this component! We currently have a few issues open that would be ideal for a community member to take and would love to have more ideas!

We are excited to release the <pwa-install /> component today! Let us know what you think and keep an eye on the PWABuilder project for more awesome stuff coming out over the next few months!


medium for PWABuilder team

Justin Willis

Written by

Program Manager at Microsoft (on the PAX Web team) helping push PWAs forward. Formerly dev relations at Ionic.


medium for PWABuilder team

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade