What You Need to Know about the Progressive Web Application Add to Homescreen or Installation Process

Add to Homescreen
Add to Homescreen

Having your icon on customer home screens it a key engagement feature.

Progressive Web Applications can launch just like a native app once they are installed or added to the homescreen.

The good news is PWA Add to Homescreen is available in all browsers on all platforms. However Browser and operating system user experience and capabilities are fragmented. 

At the same time each browser and OS update can and do change the process and capabilities.

This makes it difficult to manage as a developer and brand manager.

After creating hundreds of PWAs I have confronted this fragmentation. I am going to share some important details about what you can expect with the add to homescreen feature.

Plus you can use my Add to Homescreen library to help you negotiate all the platform volatility.

Business stakeholders love the ability for PWAs to earn a place on a visitor's home screen or desktop. This is because it signals customer engagement. This means they are more likely to purchase your products and services.

Adding your PWA icon on the home screen represents the penultimate moment where a covalent bond is forged between the brand and customer.

The brand provided enough value to the visitor for them to want your app to be a part of my digital life.

Every app, native or web, goes through a relationship funnel. In the marketing world this is better known as a sales funnel. The relationship goes through phases. Each step representing a close and closer bond.

The moment the consumer takes the step to add a progressive web app to their home screen is an intimate step. Even if it is a digital connection.

Today we don't let any brand occupy a spot on that homescreen. It has to be something we want to be a regular part of our life.

That home screen icon represents the need to make something easily accessible. Not something we want to continue to search and fumble around to open.

The homescreen icon might be the most important part of the progressive web application life cycle.

I am not one of those, but I think it is one of the most important aspects of the life cycle and a step you should seek.

At the same time this is the one aspect of the progressive web application journey that is a bit chaotic. Each browser has a different path for users to add a PWA to the home screen or desktop.

There is also a healthy debate about should we call it 'add to homescreen' or 'install'?

I think, to the user it should be phrased as 'install'. It is an explicit action on their part.

At the same time as soon as the user visits a page in the progressive web app the assets are 'installed'. The service worker should cache the core plumbing.

It is the action of responding to the install prompt completes the real install process.

So why so much fragmentation when it comes to browser and platform implementation?

Where does the term, 'add to homescreen' even come from?

The History of 'Add to Homescreen'

Apple is the company that created the term 'add to homescreen'. This is how they labeled the action in Safari on iOS.

This is where we get the term, sometimes abbreviated as 'A2HS'.

This term is still in the iOS Safari lexicon and available from the 'share icon' in iOS Safari. As years progressed Apple buried this option a little further from the 'top'. Now the user has to invoke the share icon, then swipe to the right for the option.

There is also not any sort of automated trigger like the 'beforeinstallprompt' event. It is up to you to prompt and guide the user to and through the process.

This is part of how our Add to Home screen library works.

It is a tool that detects the platform. It then displays the prompt and guidance to the user so they will know how to add your web app to their homescreen.

Apple was the first to provide a path to add web apps to the device. A few years later Google updated Chrome to honor the Apple web app META tags (I will discuss in the next section).

Today web manifest file specification provides meta or descriptive content to the browser.

Unfortunately, Apple has yet to this part of the web manifest file. Nor does iOS support the beforeinstallprompt event

iOS Add to Home screen Web Apps

The original iPhone announcement app strategy was to use web apps. Apple created the concept of 'mobile-web-app-capable' and touch icons

You could call progressive web apps the modern implementation of iPhone website apps or homescreen apps.

Apple seems to be adopting the web manifest file as the authoritative source of web app meta data. To my knowledge there has not been any public statement to the adoption of the web manifest file as a source information over classic Apple Touch Icon Meta tags. But it does seem like the icons and application name are being used when a PWA is added to the iOS homescreen over the meta tags.

For now you should include the classic iOS Mobile Web App Capable and Touch Icon meta tags.

These META tags are added to a web page to direct iOS Safari. The browser then follows how you want the web app to behave once the user has added the web app to the homescreen.

These are the core iOS web app meta tags:

  • mobile-web-app-capable
  • apple-mobile-web-app-capable
  • application-name
  • apple-mobile-web-app-title
  • apple-mobile-web-app-status-bar-style
  • apple-touch-icon

Today there is a little confusion about what to call web apps on iOS, are they web apps or web clips. Apple seems to be calling them web clips today, but that sounds a little corny to me, so I will stick with web app.

They also seem opposed to the term Progressive Web App. Instead they prefer the term, Home Screen App.

But, as far as I can tell, the iOS web app META tags don't kick in until the website is added to the iOS homescreen.


The mobile-web-app-capable META tag has one value, content="yes". If you set content to no there is no reason to have the tag in the first place.

When the tag is present and set to yes, the web app launches in full screen mode and looks just like a native app. 

This META tag tells the browser if the web app is opened from the homescreen icon then suppress or hide the browser address bar and other browser action buttons.

In fact, when I demonstrated mobile first web apps in 2009 users were amazed they were not native apps.

This is how Apple wants web apps to be, just like native apps:

A web application is designed to look and behave in a way similar to a native application—for example, it is scaled to fit the entire screen on iOS. You can tailor your web application for Safari on iOS even further, by making it appear like a native application when the user adds it to the Home screen. You do this by using settings for iOS that are ignored by other platforms.

Remember, if you make your web app launch in full screen mode you need to provide user interface affordances to facilitate navigation. This means you need to add a back button to your UI. This has proven to be a little trickier than it should be in several apps I have written, so be patient with this process.

Apple Mobile Web App Status Bar Style

The next iOS web app META tag is the 'apple-mobile-web-app-status-bar-style'.

This gives some control over the status bar style for your installed Progressive Web Application on iPhones and iPads.

The status bar is the horizontal area at the top of the screen that typically displays the battery, time and network connectivity state icons.

If you do not designate this META tag the status bar displays as solid black, no text. This is not a good experience.

Fortunately you have a limited set of options to control how the status bar renders.

There are three values, default, black and black-translucent. When default or black is selected the web app's content is displayed below the status bar.

<meta name="apple-mobile-web-app-status-bar-style" content="black">
  • default: white background with black text and icons
  • black: The default black bar with black text and icons (not recommended)
  • black-translucent: white text and icons with a transparent background.

If the black-translucent is set the content consumes the entire screen. The status bar overlays the top of the viewport as a semi-transparent overlay.

If you have a white or light background color in your web page you want to use default instead of black-translucent. The status bar text and icons will not be visible against the light background.

You must include the apple-mobile-web-app-capable META tag with a valid value for this Apple specific META tag to take affect.

Apple Touch Icon Meta Tags

iOS Add to Homescreen
iOS Add to Homescreen

The next META tag, really set of META tags is the 'apple-touch-icon'. This specifies the actual icon used on the iOS home screen to represent the web app.

In the example, which comes from the PWA Starter, demonstrates configuring a web page to reference a series of icons. The platform selects the best sized icon for the screen resolution.

You can think of it as a crude responsive image mechanism for iOS web app icons.

When a web app is launched it may have a start or splash screen, like most native apps. You can also specify the image used in this splash screen.

Personally, this is not that much of a priority for me as our apps tend to render rather quickly. So the splash screen never comes into play. If your app takes a longer to render, for example if you use React or Angular, then make sure to specify the splash screen image.

You can also specify the app name displayed on the home screen using the 'apple-mobile-web-app-title' META tag.

If this META tag is omitted, the TITLE tag is used. The TITLE value is not what you want. The title changes from page to page and should be around 60 characters.

Unfortunately, Apple has never matured the web app, home screen icon experience. We do know is adopting parts of the web manifest file. I suspect over time Safari will use the entire manifest file and the META tags will deprecate.


While the add to home screen experiences are not as fragmented as the Android operating system device ecosystem, there is still fragmentation.

The main division with Android browsers is between Chrome and all the rest. Chrome supports the 'beforeinstallprompt' event driven sequence, and the others, well they act more like iOS Safari.

The 'beforeinstallprompt' event does two things, signifies PWA qualification and initiates a process to install a progressive web app to the device.

Since I wrote about the 'beforeinstallprompt' event and how to handle it in another article I won’t dive into that here.

Instead I want to touch on why the Chrome on Android progressive web app installation process differs from the iOS web app or merely adding a bookmark icon to the homescreen.

A couple of years ago Google upgraded the PWA install process to create a WebAPK. Instead of just creating an icon on the home screen that will open the application according to the web manifest display property, it actually creates a semi-app.

To oversimplify what happens to make it easy to understand, when a PWA is installed to the home screen it is packaged within an APK, the Android app packaging. It sort of creates an Android app, but without elevating it to a full blown Android app in a hybrid wrapper.

It does this so the installed progressive web app can have access to some of the application plumbing. Specifically, so it uses the same channels or paths an app from the Play Store does when it comes to having a presence in the app shelf and settings.

I think there is a little more to the process, but they are not as important for general understanding. The main takeaways are the user can access the PWA not only from the homescreen, but the app shelf and can 'uninstall' the PWA just like a native app. The user can also manage storage, notifications and other settings just like native apps.

The boundary, if you will, is the PWA does not get access to platform specific APIs like a native app would. But honestly, today the differences between native apps and PWAs are so minimal there is not a lot that could be gained by providing access to the platform specific APIs anyway.

So you are left with a PWA installed using Chrome on Android is a full blow native app, just without the Play Store or some private app store involved!

Non-Chrome Browsers Add to Homescreen

Unfortunately, even though Google has made the WebAPK plumbing available for other browsers to use, they haven't.

And it is frustrating.

Instead of a nice event driven installation process the user must fumble around to add the PWA to their device homescreen, just like iOS.

Addressbar PWA Icon Example
Address Bar PWA Icon Example

Some browsers, like FireFox, Opera and Samsung Internet will display an icon in their address bar to indicate the site can be added to the home screen as a PWA, but no one outside of the hard core PWA fanboys like me know this is a thing.

Sure a few people will hit the icon to see what happens, but for the most part consumers are not so fearless and would not want to risk triggering something that will 'break' their phone if you will.

This leaves it up to use to 'guide' the user to the settings menu or the icon to let them know how to add to the home screen and that it is 'safe' for them to do.

After the PWA is installed it will launch according to the web manifest values, but they are not WebAPKs. This means no settings control or app shelf presence. Just an icon on the homescreen, usually with the browser's icon overlaid in a corner of the application's home screen icon.

Again, this is something the Add to Home screen library helps to abstract away so you can prompt the user with graphics and instructions for a specific browser.

Add Progressive Web App to Desktop

To confuse you even a little more let's talk about adding a progressive web app to your PC or Mac desktop. Notice, not add to homescreen, since well we don't call it a home screen on our laptops.

Chrome and the Chromium based Edge will add the PWA"s icon to the desktop in response to the 'beforeinstallprompt' sequence. You will even see the application listed in the Windows start menu application list.

The PWA is also present in Windows application uninstall list, which means you can 'remove' it from the computer.

You can also pin a PWA to the taskbar, just like any other app.

Install PWA From Menu
Install PWA From Menu

What we don't have are Windows Live Tile support or the old pinned sites features we had when a web site was pinned to the task bar using the now deprecated Internet Explorer.

Installed progressive web apps will launch according the web manifest display property, which for me means standalone mode. So, they launch just like a regular application.

Other than Chrome and new Edge the other browsers have a similar store as they do on Android. You have to provide some sort of way point based map to guide them to the settings menus to install the PWA.


The Add to Home screen or Install step is an important part of the Progressive Web Application engagement life-cycle. You just have to understand how the experience is fragmented and provide an appropriate experience to guide the user to install your application.

You may need to exercise some control over this experience so the user is not constantly prompted, but prompted when appropriate. This is why using an Add to Home screen tool like our library can give you control over the prompt timing and messaging to guide the user through the process.

Because you are trying to connect with your customer you need to make sure they are comfortable with the install process. They not only need to know how to do it, but also know it is safe.

My hope is someday soon all browsers will not only support the 'beforeinstallprompt' event, but will also support some form of the WebAPK. This will give us a fair shot at progressive web applications have that final piece of parity we need to leverage native app capabilities. For now, we are close enough, just fragmented.

Share This Article With Your Friends!

We use cookies to give you the best experience possible. By continuing, we'll assume you're cool with our cookie policy.

Install Love2Dev for quick, easy access from your homescreen or start menu.

Googles Ads Bing Pixel LinkedIn Pixel