MDN wants to learn about developers like you: https://qsurvey.mozilla.com/s3/MDN-survey

App Center

Add to Home screen

Add to Home screen (or A2HS for short) is a feature available in modern smartphone browsers that allows developers to easily and conveniently add a shortcut to their Home screen representing their favorite web app (or site) so they can subsequently access it with a single tap. This guide explains how A2HS is used, and what you need to do as a developer to allow your users to take advantage of it.

Why A2HS?

A2HS is thought to be part of the Progressive Web App philosophy — giving web apps the same user experience advantages as native apps so they can compete in today's ecosystem wars. Part of this is the simple matter of accessing an app by tapping on its nice shiny icon on your Home screen, and having it appear neatly in its own window. This is what A2HS makes possible.

What browsers support A2HS?

A2HS is supported by Mobile Chrome/Android Webview since version 31, Opera for Android since version 32, and Firefox for Android since version 58.

How do you use it?

We've written a very simple example web site (see our demo live, and also see the source code) that doesn't do much, but is developed with the necessary code to allow it to be added to home screen as well as a service worker to allow it to be used offline. It displays a series of fox pictures:

If you have Firefox for Android available, use it to navigate to our demo at https://mdn.github.io/pwa-examples/a2hs/ . You'll see fox pictures, but more importantly you'll a see a "home" icon with a plus (+) icon inside it — this is the "Add to Home screen" icon, displayed for any site that has the necessary features in place.

Tapping this will show a confirmation banner — pressing the big + ADD TO HOME SCREEN button completes the action, adding the app to the Home screen. (Note: in Android 8 and higher, a system-level "Add to Home screen" permission dialog will be shown first.)

If you have Mobile Chrome available, the experience is slightly different — upon loading our site, you'll see an install banner pop up, asking you whether you want to add this app to your Home screen.

Note: You can find a lot more out about Chrome install banners at the article Web App Install Banners.

If you choose not to add it to Home screen at this point, you can choose to later on using the Add to Home screen icon in the main Chrome menu.

Regardless of which browser you are using, when you choose to add the app to your Home screen, you'll see it appear along with a short title, in the same way that native apps do.

Tapping on this icon opens it up, but as a fullscreen app — you'll no longer see the browser UI around it.

How do you make an app A2HS-ready?

To make it so your app can be added to Home screen, it needs the following:

  • To be served over HTTPs — the web is increasingly being moved in a more secure direction, and many modern web technologies (A2HS included) will only work on secure contexts.
  • To have a manifest file with the correct fields filled in.
  • To have an appropriate icon available for displaying on the Home screen.
  • Chrome additionally requires the app to have a service worker registered (e.g. so it can function when offline).

Manifest

The web manifest is written in standard JSON format and should be placed somewhere inside your app directory (in the root is probably best) with a name of manifest.webmanifest. It contains multiple fields that define certain information about the web app and how it should behave.

The fields needed for A2HS are as follows:

  • background_color: Specifies a background color to be used in some app contexts. The most relevant one to A2HS is the splash screen displayed when the app icon on the Home screen is tapped and it first starts to load (this currently only appears when apps have been added to the Home screen by Chrome).
  • display: Specifies how the app should be displayed. To make it feel like a distinct app (and not just a web page), you should choose a value such as fullscreen (no UI is shown at all), or standalone (very similar, but system-level UI elements like the status bar might be visible).
  • icons: Specifies icons for the browser to use when representing the app in different places (such as on the task switcher, or more importantly the home screen). We've only included one in our demo.
  • name/short_name: These fields provide an app name to be displayed when representing the app in different places. name provides the full app name, and short_name provides a shortened name to be used when there is insufficient space to display the full name. You are advised to provide both if your app's name is particularly long.
  • start_url: Provides a path to the asset that should be loaded when the added-to-Home screen app is launched. Note that this has to be a relative URL pointing to the site index, relative to the origin of the site. Note that Chrome requires this before it will display the install banner, whereas Firefox doesn't require it for showing the home-with-a-plus icon.

The manifest for our sample app looks like so:

{
  "background_color": "purple",
  "description": "Shows random fox pictures. Hey, at least it isn't cats.",
  "display": "fullscreen",
  "icons": [
    {
      "src": "icon/fox-icon.png",
      "sizes": "192x192",
      "type": "image/png"
    }
  ],
  "name": "Awesome fox pictures",
  "short_name": "Foxes",
  "start_url": "/pwa-examples/a2hs/index.html"
}

Appropriate icon

As shown in the above manifest listing, we are including a 192x192px icon for use in our app. You can include more sizes if you want to; Android will choose the most appropriate size for each different use case. You could also choose to include different types of icon so devices can use the best one they are able to (e.g. Chrome already supports the WebP format).

Note that the type member in each icon's object specifies the icon's mimetype, so the browser can quickly read what the type the icon is, and ignore it and move on to a different icon if it doesn't support it.

In terms of how to design the icon, you should follow the same best practices as you'd follow for any Android icon (See the Android icon design guidelines).

What does A2HS not give you?

Bear in mind that when you add an app to your Home screen, it just makes the app easily accessible from the Home screen — it doesn't download the app's assets and data to your device and make the app available offline, or anything like that. To make your app work offline, you have to use the Service Worker API to handle storing the assets offline, and if required, Web storage or IndexedDB to store its data.

In our example app we've just used a service worker to store all necessary files. The service worker is registered against the site with the final code block in the index.js file. We then cache all the site assets using the Cache API, and then serve them from the cache instead of the network, using the code in the sw.js file.

See also

Document Tags and Contributors

 Contributors to this page: chrisdavidmills, andreasbovens
 Last updated by: chrisdavidmills,