Pete LePage on web.dev

How Chrome handles updates to the web app manifest

2020-10-14T00:00:00Z

When a PWA is installed, the browser uses information from the web app manifest for the app name, the icons the app should use, and the URL that should be opened when the app is launched. But what if you need to update app shortcuts or try a new theme color? When and how are those changes reflected in the browser?

In most cases, changes should be reflected within a day or two of the PWA being launched, after the manifest has been updated.

Updates on desktop Chrome #

When the PWA is launched, or opened in a browser tab, Chrome determines the last time the local manifest was checked for changes. If the manifest hasn't been checked since the browser last started, or it hasn't been checked in the last 24 hours, Chrome will make a network request for the manifest, then compare it against the local copy.

If select properties in the manifest have changed (see list below), Chrome queues the new manifest, and after all windows have been closed, installs it. Once installed, all fields from the new manifest (except name, short_name, and icons) are updated.

Which properties will trigger an update? #

display (see below)
scope
shortcuts
start_url
theme_color
file_handlers

What happens when the `display` field is updated? #

If you update your app's display mode from browser to standalone your existing users will not have their apps open in a window after updating. There are two display settings for a web app, the one from the manifest (that you control) and a window/browser tab setting controlled by the user. The user preference is always respected.

Testing manifest updates #

The chrome://web-app-internals page (available in Chrome 85 or later), includes detailed information about all of the PWAs installed on the device, and can help you understand when the manifest was last updated, how often it's updated, and more.

To manually force Chrome to check for an updated manifest, you can either launch Chrome with the command line flag --disable-manifest-update-throttle or restart Chrome (use about://restart), this resets the timer so that Chrome will check for an updated manifest when the PWA is next launched. Then launch the PWA. After closing the PWA, it should be updated with the new manifest properties.

References #

Updatable Web Manifest Fields

Updates on Chrome for Android #

When the PWA is launched, Chrome determines the last time the local manifest was checked for changes. If the manifest hasn't been checked in the last 24 hours, Chrome will schedule a network request for the manifest, then compare it against the local copy.

If select properties in the manifest have changed (see list below), Chrome queues the new manifest, and after all windows of the PWA have been closed, the device is plugged in, and connected to WiFi, Chrome requests an updated WebAPK from the server. Once updated, all fields from the new manifest are used.

Which properties will trigger an update? #

background_color
display
orientation
scope
shortcuts
start_url
theme_color
web_share_target

If Chrome is unable to get an updated manifest from the server, it may increase the time between checks to 30 days.

Testing manifest updates #

The about://webapks page includes detailed information about all of the PWAs installed on the device, and can tell you when the manifest was last updated, how often it's updated, and more.

To manually schedule an update to the manifest, overriding the timer and local manifest do the following:

Plug in the device and ensure it's connected to WiFi.
Use the Android task manager to shut down the PWA, then use the App panel in Android settings to force stop the PWA.
In Chrome, open about://webapks and click the "Update" button for the PWA. "Update Status" should change to "Pending".
Launch the PWA, and verify it's loaded properly.
Use the Android task manager to shut down the PWA, then use the App panel in Android settings to force stop the PWA.

The PWA usually updates within a few minutes, once the update has completed, "Update Status" should change to "Successful"

References #

UpdateReason enum for Chrome on Android

Create an offline fallback page

2020-09-24T00:00:00Z

What do the Google Assistant app, the Slack app, the Zoom app, and almost any other platform-specific app on your phone or computer have in common? Right, they always at least give you something. Even when you do not have a network connection, you can still open the Assistant app, or enter Slack, or launch Zoom. You might not get anything particularly meaningful or even be unable to achieve what you wanted to achieve, but at least you get something and the app is in control.

Google Assistant.

Slack.

Zoom.

With platform-specific apps, even when you do not have a network connection, you never get nothing.

In contrast, on the Web, traditionally you get nothing when you are offline. Chrome gives you the offline dino game, but that is it.

Google Chrome for iOS.

Google Chrome for macOS.

On the Web, when you do not have a network connection, by default you get nothing.

An offline fallback page with a custom service worker #

It does not have to be this way, though. Thanks to service workers and the Cache Storage API, you can provide a customized offline experience for your users. This can be a simple branded page with the information that the user is currently offline, but it can just as well be a more creative solution, like, for example, the famous trivago offline maze game with a manual Reconnect button and an automatic reconnection attempt countdown.

The trivago offline maze.

Registering the service worker #

The way to make this happen is through a service worker. You can register a service worker from your main page as in the code sample below. Usually you do this once your app has loaded.

window.addEventListener("load", () => {
  if ("serviceWorker" in navigator) {
    navigator.serviceWorker.register("service-worker.js");
  }
});

The service worker code #

The contents of the actual service worker file may seem a little involved at first sight, but the comments in the sample below should clear things up. The core idea is to pre-cache a file named offline.html that only gets served on failing navigation requests, and to let the browser handle all other cases:

/*
Copyright 2015, 2019, 2020, 2021 Google LLC. All Rights Reserved.
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at
 http://www.apache.org/licenses/LICENSE-2.0
 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
*/

// Incrementing OFFLINE_VERSION will kick off the install event and force
// previously cached resources to be updated from the network.
// This variable is intentionally declared and unused.
// Add a comment for your linter if you want:
// eslint-disable-next-line no-unused-vars
const OFFLINE_VERSION = 1;
const CACHE_NAME = "offline";
// Customize this with a different URL if needed.
const OFFLINE_URL = "offline.html";

self.addEventListener("install", (event) => {
  event.waitUntil(
    (async () => {
      const cache = await caches.open(CACHE_NAME);
      // Setting {cache: 'reload'} in the new request ensures that the
      // response isn't fulfilled from the HTTP cache; i.e., it will be
      // from the network.
      await cache.add(new Request(OFFLINE_URL, { cache: "reload" }));
    })()
  );
  // Force the waiting service worker to become the active service worker.
  self.skipWaiting();
});

self.addEventListener("activate", (event) => {
  event.waitUntil(
    (async () => {
      // Enable navigation preload if it's supported.
      // See https://developers.google.com/web/updates/2017/02/navigation-preload
      if ("navigationPreload" in self.registration) {
        await self.registration.navigationPreload.enable();
      }
    })()
  );

  // Tell the active service worker to take control of the page immediately.
  self.clients.claim();
});

self.addEventListener("fetch", (event) => {
  // Only call event.respondWith() if this is a navigation request
  // for an HTML page.
  if (event.request.mode === "navigate") {
    event.respondWith(
      (async () => {
        try {
          // First, try to use the navigation preload response if it's
          // supported.
          const preloadResponse = await event.preloadResponse;
          if (preloadResponse) {
            return preloadResponse;
          }

          // Always try the network first.
          const networkResponse = await fetch(event.request);
          return networkResponse;
        } catch (error) {
          // catch is only triggered if an exception is thrown, which is
          // likely due to a network error.
          // If fetch() returns a valid HTTP response with a response code in
          // the 4xx or 5xx range, the catch() will NOT be called.
          console.log("Fetch failed; returning offline page instead.", error);

          const cache = await caches.open(CACHE_NAME);
          const cachedResponse = await cache.match(OFFLINE_URL);
          return cachedResponse;
        }
      })()
    );
  }

  // If our if() condition is false, then this fetch handler won't
  // intercept the request. If there are any other fetch handlers
  // registered, they will get a chance to call event.respondWith().
  // If no fetch handlers call event.respondWith(), the request
  // will be handled by the browser as if there were no service
  // worker involvement.
});

The offline fallback page #

The offline.html file is where you can get creative and adapt it to your needs and add your branding. The example below shows the bare minimum of what is possible. It demonstrates both manual reload based on a button press as well as automatic reload based on the online event and regular server polling.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>You are offline</title>

    <!-- Inline the page's stylesheet. -->
    <style>
      body {
        font-family: helvetica, arial, sans-serif;
        margin: 2em;
      }

      h1 {
        font-style: italic;
        color: #373fff;
      }

      p {
        margin-block: 1rem;
      }

      button {
        display: block;
      }
    </style>
  </head>
  <body>
    <h1>You are offline</h1>

    <p>Click the button below to try reloading.</p>
    <button type="button">⤾ Reload</button>

    <!-- Inline the page's JavaScript file. -->
    <script>
      // Manual reload feature.
      document.querySelector("button").addEventListener("click", () => {
        window.location.reload();
      });

      // Listen to changes in the network state, reload when online.
      // This handles the case when the device is completely offline.
      window.addEventListener('online', () => {
        window.location.reload();
      });

      // Check if the server is responding and reload the page if it is.
      // This handles the case when the device is online, but the server
      // is offline or misbehaving.
      async function checkNetworkAndReload() {
        try {
          const response = await fetch('.');
          // Verify we get a valid response from the server
          if (response.status >= 200 && response.status < 500) {
            window.location.reload();
            return;
          }
        } catch {
          // Unable to connect to the server, ignore.
        }
        window.setTimeout(checkNetworkAndReload, 2500);
      }

      checkNetworkAndReload();
    </script>
  </body>
</html>

Demo #

You can see the offline fallback page in action in the demo embedded below. If you are interested, you can explore the source code on Glitch.

Side note on making your app installable #

Now that your site has an offline fallback page, you might wonder about next steps. To make your app installable, you need to add a web app manifest and optionally come up with an install strategy.

Side note on serving an offline fallback page with Workbox.js #

You may have heard of Workbox. Workbox is a set of JavaScript libraries for adding offline support to web apps. If you prefer to write less service worker code yourself, you can use the Workbox recipe for an offline page only.

Up next, learn how to define an install strategy for your app.

How to file a good browser bug

2020-06-15T00:00:00Z

Filing a good bug isn't hard, but takes a little work. The goal is to make it easy to find what's broken, reach the root cause and, most importantly, find a way to fix it. Bugs that make fast progress tend to be easy to reproduce with a clear expected behavior.

Verify it is a bug #

The first step is to figure out what the "correct" behavior should be.

What's the correct behavior? #

Check the relevant API docs on MDN, or try to find related specs. This information can help you decide which API is actually broken, where it's broken, and what the expected behavior is.

Does it work in a different browser? #

Behavior that differs between browsers is generally prioritized higher as an interoperability issue, especially when the browser containing the bug is the odd one out. Try to test on the latest versions of Chrome, Firefox, Safari and Edge, possibly using a tool like BrowserStack.

If possible, check that the page isn't intentionally behaving differently due to user agent sniffing. In Chrome DevTools, try setting the User-Agent string to another browser.

Did it break in a recent release? #

Did this work as expected in the past, but broke in a recent browser release? Such "regressions" can be acted upon much quicker, especially if you supply a version number where it worked and a version where it failed. Tools like BrowserStack can make it easy to check old browser versions and the bisect-builds tool (for Chromium) allows searching for the change very efficiently.

If an issue is a regression and can be reproduced, the root cause can usually be found and fixed quickly.

Are others seeing the same problem? #

If you're experiencing problems, there's a good chance other developers are too. First, try searching for the bug on Stack Overflow. This might help you translate an abstract problem into a specific broken API, and it might help you find a short term workaround until the bug is fixed.

Has it been reported before? #

Once you have an idea of what the bug is, it's time to check to see if the bug has already been reported by searching the browser bug database.

Chromium-based browsers: https://crbug.com
Firefox: https://bugzilla.mozilla.org/
Safari & WebKit-based browsers: https://bugs.webkit.org/

If you find an existing bug that describes the problem, add your support by starring, favoriting, or commenting on the bug. And, on many sites, you can add yourself to the CC list and get updates when the bug changes.

If you decide to comment on the bug, include information about how the bug affects your website. Avoid adding "+1" style comments, as bug trackers typically send emails for every comment.

Report the bug #

If the bug hasn't been reported before, it's time to tell the browser vendor about it.

Create a minimized test case #

Mozilla has a great article on how to create a minimized test case. To make a long story short, while a description of the problem is a great start, nothing beats providing a linked demo in the bug that shows the problem. To maximize the chance of fast progress the example should contain the minimum possible code needed to demonstrate the problem. A minimal code sample is the number one thing you can do to increase the odds of your bug getting fixed.

Here are a few tips for minimizing a test case:

Download the web page, add <base href="https://original.url"> and verify that the bug exists locally. This may require a live HTTPS server if the URL uses HTTPS.
Test the local files on the latest builds of as many browsers as you can.
Try to condense everything into 1 file.
Remove code (starting with things you know to be unnecessary) until the bug goes away.
Use version control so that you can save your work and undo things that go wrong.

Hosting a minified test case #

If you're looking for a good place to host your minified test case, there are several good places available:

Be aware that several of those sites display content in an iframe, which may cause features or bugs to behave differently.

Filing your issue #

Once you've got your minimized test case, you're ready to file that bug. Head over to the right bug tracking site, and create a new issue.

Chromium-based browsers - https://crbug.com/new
Firefox - https://bugzilla.mozilla.org/
Safari & WebKit-based browsers - https://bugs.webkit.org/

Provide a clear description and the steps required to reproduce the issue #

First, provide a clear description to help engineers quickly understand what the problem is and help to triage the issue.

When installing a PWA using the `beforeinstallprompt.prompt()`, the
`appinstalled` event fires before the call to `prompt()` resolves.

Next, provide the detailed steps required to reproduce the issue. This is where your minified test case comes in.

What steps will reproduce the problem?
1. Go to https://basic-pwa.glitch.me/, open DevTools and look at the
   console tab.
2. Click the Install button in the page, you might need to interact with
   the page a bit before it becomes enabled.
3. Click Install on the browser modal install confirmation.

And finally, describe the expected, and actual result.

What is the expected result? In the console:
0. INSTALL: Available (logged when `beforeinstallprompt` event fired)
1. INSTALL_PROMPT_RESPONSE: {outcome: "accepted", platform: "web"}
   (logged when beforeinstallprompt.prompt()` resolves)
2. INSTALL: Success (logged when `appinstalled` event fired)

What is the actual result? In the console:
0. INSTALL: Available (logged when `beforeinstallprompt` event fired)
1. INSTALL: Success (logged when `appinstalled` event fired)
2. INSTALL_PROMPT_RESPONSE: {outcome: "accepted", platform: "web"}
   (logged when beforeinstallprompt.prompt()` resolves)

For more information, check out Bug report writing guidelines on MDN.

Bonus: Add a screenshot or screencast of the issue #

Though not required, in some cases, it can be helpful to add a screenshot, or screencast of the issue. This is especially helpful in cases where bugs may require some odd steps to reproduce. Being able to see what happens in a screencast, or on a screenshot can frequently be helpful.

Include details of the environment #

Some bugs are reproducible only on certain operating systems, or only on specific kinds of displays (for example, low-dpi or high-dpi). Be sure to include the details of any test environments you used.

Submit the bug #

Finally, submit the bug. Then, remember to keep an eye on your email for any responses to the bug. Typically during investigation and when fixing the bug, engineers may have additional questions, or if they have difficulty reproducing the issue, they may reach out.

How to define your install strategy

2020-05-12T00:00:00Z

In the past, app installation was only possible in the context of platform-specific applications. Today, modern web apps offer installable experiences that provide the same level of integration and reliability as platform-specific apps.

You can achieve this in different ways:

Installing the PWA from the browser.
Installing the PWA from the app store.

Having different distribution channels is a powerful way of reaching a broad number of users, but choosing the right strategy to promote your the installation of your PWA can be challenging.

This guide explores best practices for combining different installation options to increase installation rates and avoid platform competition and cannibalization. The installation offerings covered include PWAs installed from both the browser and the App Store, as well as platform-specific apps.

Why make your web app installable? #

Installed Progressive Web Apps run in a standalone window instead of a browser tab. They're launchable from the user's home screen, dock, taskbar, or shelf. It's possible to search for them on a device and jump between them with the app switcher, making them feel like part of the device they're installed on.

But having both an installable web app and a platform-specific app can be confusing for users. For some users platform-specific apps may be the best choice, but for others they can present some drawbacks:

Storage constraints: installing a new app might mean deleting others, or cleaning up space, by removing valuable content. This is especially disadvantageous for users on low-end devices.
Available bandwidth: downloading an app can be a costly and slow process, even more so for users on slow connections and expensive data plans.
Friction: leaving a website and moving to a store to download an app creates additional friction and delays a user action that could be performed directly in the web.
Update cycle: making changes in platform-specific apps might require going through an app review process, which can slow down changes and experiments (A/B tests, for example).

In some cases, the percentage of users who won't download your platform-specific app might be large, for example: those that think that they won't use the app very often, or can't justify spending several megabytes of storage or data. You can determine the size of this segment in several ways, for example by using an analytics setup to track the percentage of "mobile web only" users.

If the size of this segment is considerable, that's a good indication that you need to provide alternative ways of installing your experiences.

Promoting installation of your PWA through the browser #

If you have a high quality PWA, it may be better to promote its installation over your platform-specific app. For example, if the platform-specific app is missing functionality offered by your PWA, or if it hasn't been updated in a while. It can also be helpful to promote installation of your PWA if the platform-specific app wasn't optimized for bigger screens, such as on ChromeOS.

For some apps, driving platform-specific app installations is a key part of the business model, in that case, it makes business sense to promote installation of your platform-specific app. But, some users might be more comfortable staying on the web. If that segment can be identified, the PWA prompt can be shown only to them (what we call "PWA as fallback").

PWA as primary installable experience #

Once a PWA meets the installability criteria, most browsers show an indication that the PWA is installable. For example, desktop Chrome shows an installable icon in the address bar, and on mobile, it shows a mini-infobar:

The mini-infobar.

While that may be enough for some experiences, if your goal is to drive installations of your PWA, we highly recommend you listen for the BeforeInstallPromptEvent, and follow the patterns for promoting the installation of your PWA.

Prevent your PWA from cannibalizing your platform-specific app install rate #

In some cases, you may choose to promote the installation of your platform-specific app over your PWA, but in this case, we still recommend you provide a mechanism to allow users to install your PWA. This fallback option makes it possible for users who can't, or don't want to install your platform-specific app to get a similar, installed experience.

The first step to implement this strategy is to define a heuristic for when you'll show the user an install promotion for your PWA.

For example: A PWA user is a user that has seen the platform-specific app install prompt and not installed the platform-specific app. They have returned to the site at least five times, or they have clicked the app banner, but have continued using the website instead.

Then, the heuristic can be implemented in the following way:

Show the platform-specific app install banner.
If a user dismisses the banner, set a cookie with that information (e.g. document.cookie = "app-install-banner=dismissed").
Use another cookie to track the number of user visits to the site (e.g. document.cookie = "user-visits=1").
Write a function, such as isPWAUser(), that uses the information previously stored in the cookies along with the getInstalledRelatedApps() API to determine if a user is considered a "PWA user".
When the user performs a meaningful action, call isPWAUser(). If the function returns true and the PWA install prompt was saved previously, you can show the PWA install button.

Promoting installation of your PWA through an app store #

Apps for App stores can be built with different technologies, including PWA techniques. In Blending PWA into native environments you can find a summary of the technologies that can be used to that end.

In this section we'll classify apps in the store in two groups:

Platform-specific apps: these apps are mostly built with platform-specific code. Their sizes depend on the platform, but they're usually above 10MB on Android, and 30MB on iOS. You might want to promote your platform-specific app if you don't have a PWA, or if the platform-specific app presents a more complete feature set.
Lightweight apps: these apps can be built with platform-specific code as well, but they are commonly built with web technology, packaged in a platform-specific wrapper. Full PWAs can be uploaded to the stores as well. (This is discussed later in this article.) Some companies opt to provide these as "lite" experiences, and others have used this approach for their flagship (core) apps as well.

Promoting Lightweight Apps #

According to a Google Play study, for every 6 MB increase to an APK's size, the install conversion rate decreases by 1%. This means that the download completion rate of an app of 10 MB could be approximately 30% higher than an app of 100 MB!

To address this, some companies are leveraging their PWA to provide a lightweight version of their app in the Play Store using Trusted Web Activities (TWA). TWAs wrap your PWA in a webview like component, and the resulting app size is usually only a few megabytes.

Oyo, one of India's largest hospitality companies, built a Lite version of their app, and made it available in the Play Store using a TWA. At the time this article was written, the Oyo app was only 850 KB, just 7% the size of their Android app. And once installed, it's indistinguishable from their Android app:

OYO Lite in action.

Oyo kept both the flagship and "lite" app versions in the store, providing a choice to their users.

Providing a lightweight web experience #

Intuitively, users on low-end devices, might be more inclined to download lightweight versions of apps than users on high-end phones. Therefore, if it's possible to identify a user's device, you could prioritize the lightweight app install banner over the heavier platform-specific app version.

On the web, it's possible to obtain device signals and approximately map them to device categories (e.g. "high", "mid", or "low"). You can obtain this information in different ways, using either JavaScript APIs or client hints.

Using JavaScript #

Using JavaScript properties such as navigator.hardwareConcurrency, navigator.deviceMemory, and navigator.connection you can get information about the device CPU, memory and network status respectively. For example:

const deviceCategory = req.get('Device-Memory') < 1 ? 'lite' : 'full';`

Using client hints #

Device signals can be also inferred in HTTP request headers, through client hints. Here's how you can implement the previous code for device memory with client hints:

First, tell the browser you are interested in receiving device memory hints in the header of the HTTP response for any first-party request:

HTTP/1.1 200 OK
Content-Type: text/html
Accept-CH: Device-Memory

Then, you'll start receiving Device-Memory information in the request header of HTTP requests:

GET /main.js HTTP/1.1
Device-Memory: 0.5

You can use this information in your backends to store a cookie with the category of the user's device:

app.get('/route', (req, res) => {
  // Determine device category

 const deviceCategory = req.get('Device-Memory') < 1 ? 'lite' : 'full';

  // Set cookie
  res.setCookie('Device-Category', deviceCategory);
  …
});

Finally, create your own logic to map this information to device categories, and show the corresponding app install prompt on each case:

if (isDeviceMidOrLowEnd()) {
   // show "Lite app" install banner or PWA A2HS prompt
} else {
  // show "Core app" install banner
}

Conclusion #

The ability to have an icon in the user's home screen is one of the most engaging features of applications. Given that historically this was only possible for apps installed from app stores, companies might think that showing an app store install banner would be enough to convince users to install their experiences. Currently there are more options for letting users install an app, including offering lightweight app experiences in the stores, and letting users add PWAs to the home screen by prompting them to do it directly from the website.

Persistent storage

2020-05-12T00:00:00Z

When faced with storage pressure like low disk space, browsers will typically evict data, including from the Cache API and IndexedDB, from the least recently used origin. This may cause data loss if the app hasn't synced data with the server, and reduce the reliability of the app by removing resources required for the app to work, both of which lead to negative user experiences.

Thankfully, research by the Chrome team shows that data is very rarely cleared automatically by Chrome. It is far more common for users to manually clear storage. Thus if a user visits your site regularly, the chances are small that your data will be evicted. To prevent the browser from deleting your data, you can request that your entire site's storage be marked persistent.

Persistent storage is supported in many modern browsers.

Browser support

Chrome 55, Supported 55
Firefox 57, Supported 57
Edge 79, Supported 79
Safari 15.2, Supported 15.2

Source

To learn more about eviction, how much you can store, and how to handle quota limitations, see Storage for the web.

Check if your site's storage has been marked as persistent #

You can use JavaScript to determine if your site's storage has been marked as persistent. Calling navigator.storage.persisted() returns a Promise that resolves with a boolean, indicating whether storage has been marked as persisted.

// Check if site's storage has been marked as persistent
if (navigator.storage && navigator.storage.persist) {
  const isPersisted = await navigator.storage.persisted();
  console.log(`Persisted storage granted: ${isPersisted}`);
}

When should I ask for persistent storage? #

The best time to request your storage be marked as persistent is when you save critical user data, and the request should ideally be wrapped in a user gesture. Do not ask for persistent storage on page load, or in other bootstrap code, the browser may prompt the user for permission. If the user isn't doing anything that they think needs to be saved, the prompt may be confusing, and they'll likely reject the request. Additionally, don't prompt too frequently. If the user decided not to grant permission, don't immediately prompt again on the next save.

Request persistent storage #

To request persistent storage for your site's data, call navigator.storage.persist(). It returns a Promise that resolves with a boolean, indicating whether the persistent storage permission was granted.

// Request persistent storage for site
if (navigator.storage && navigator.storage.persist) {
  const isPersisted = await navigator.storage.persist();
  console.log(`Persisted storage granted: ${isPersisted}`);
}

How is permission granted? #

Persistent storage is treated as a permission. Browsers use different factors to decide whether to grant persistent storage permissions.

Chrome and other Chromium-based browsers #

Chrome, and most other Chromium-based browsers automatically handle the permission request, and do not show any prompts to the user. Instead, if a site is considered important, the persistent storage permission is automatically granted, otherwise it is silently denied.

The heuristics to determine if a site is important include:

How high is the level of site engagement?
Has the site been installed or bookmarked?
Has the site been granted permission to show notifications?

If the request was denied, it can be requested again later and will be evaluated using the same heuristics.

Firefox #

Firefox delegates the permission request to the user. When persistent storage is requested, it prompts the user with a UI popup asking if they will allow the site to store data in persistent storage.

A popup shown by Firefox when a site requests persistent storage.

What storage is protected by persistent storage? #

If the persistent storage permission is granted, the browser will not evict data stored in:

Cache API
Cookies
DOM Storage (Local Storage)
File System API (browser-provided and sandboxed file system)
IndexedDB
Service workers
App Cache (deprecated, should not be used)
WebSQL (deprecated, should not be used)

How to turn off persistent storage #

At this time, there is no programmatic way to tell the browser you no longer need persistent storage.

Conclusion #

Research from the Chrome team shows that although possible, stored data is rarely cleared automatically by Chrome. To protect critical data that may not be stored in the cloud, or will result in significant data loss, persistent storage can be a helpful tool to ensure that your data is not removed by the browser when the local device is faced with storage pressure. And remember, only request persistent storage when the user is most likely to want it.

Thanks #

Special thanks to Victor Costan, and Joe Medley for reviewing this article. Thanks to Chris Wilson who wrote the original version of this article that first appeared on WebFundamentals.

Hero image by Umberto on Unsplash

Storage for the web

2020-04-27T00:00:00Z

Internet connections can be flakey or non-existent on the go, which is why offline support and reliable performance are common features in progressive web apps. Even in perfect wireless environments, judicious use of caching and other storage techniques can substantially improve the user experience. There are several ways to cache your static application resources (HTML, JavaScript, CSS, images, etc.), and data (user data, news articles, etc.). But which is the best solution? How much can you store? How do you prevent it from being evicted?

What should I use? #

Here's a general recommendation for storing resources:

For the network resources necessary to load your app and file-based content, use the Cache Storage API (part of service workers).
For other data, use IndexedDB (with a promises wrapper).

IndexedDB and the Cache Storage API are supported in every modern browser. They're both asynchronous, and will not block the main thread. They're accessible from the window object, web workers, and service workers, making it easy to use them anywhere in your code.

What about other storage mechanisms? #

There are several other storage mechanisms available in the browser, but they have limited use and may cause significant performance issues.

SessionStorage is tab specific, and scoped to the lifetime of the tab. It may be useful for storing small amounts of session specific information, for example an IndexedDB key. It should be used with caution because it is synchronous and will block the main thread. It is limited to about 5MB and can contain only strings. Because it is tab specific, it is not accessible from web workers or service workers.

LocalStorage should be avoided because it is synchronous and will block the main thread. It is limited to about 5MB and can contain only strings. LocalStorage is not accessible from web workers or service workers.

Cookies have their uses, but should not be used for storage. Cookies are sent with every HTTP request, so storing anything more than a small amount of data will significantly increase the size of every web request. They are synchronous, and are not accessible from web workers. Like LocalStorage and SessionStorage, cookies are limited to only strings.

The File System API and FileWriter API provide methods for reading and writing files to a sandboxed file system. While it is asynchronous, it is not recommended because it is only available in Chromium-based browsers.

The File System Access API was designed to make it easy for users to read and edit files on their local file system. The user must grant permission before a page can read or write to any local file, and permissions are not persisted across sessions.

WebSQL should not be used, and existing usage should be migrated to IndexedDB. Support has been removed from almost all major browsers. The W3C stopped maintaining the Web SQL spec in 2010, with no plans to further updates planned.

Application Cache should not be used, and existing usage should be migrated to service workers and the Cache API. It has been deprecated and support will be removed from browsers in the future.

How much can I store? #

In short, a lot, at least a couple of hundred megabytes, and potentially hundreds of gigabytes or more. Browser implementations vary, but the amount of storage available is usually based on the amount of storage available on the device.

Chrome allows the browser to use up to 80% of total disk space. An origin can use up to 60% of the total disk space. You can use the StorageManager API to determine the maximum quota available. Other Chromium-based browsers may be different.
- In incognito mode, Chrome reduces the amount of storage an origin can use to approximately 5% of the total disk space.
- If the user has enabled "Clear cookies and site data when you close all windows" in Chrome, the storage quota is significantly reduced to a maximum of approximately 300MB.
- See PR #3896 for details about Chrome's implementation.
Internet Explorer 10 and later can store up to 250MB and will prompt the user when more than 10MB has been used.
Firefox allows the browser to use up to 50% of free disk space. An eTLD+1 group (e.g., example.com, www.example.com and foo.bar.example.com) may use up to 2GB. You can use the StorageManager API to determine how much space is still available.
Safari (both desktop and mobile) appears to allow about 1GB. When the limit is reached, Safari will prompt the user, increasing the limit in 200MB increments. I was unable to find any official documentation on this.
- If a PWA is added to the home screen on mobile Safari, it appears to create a new storage container, and nothing is shared between the PWA and mobile Safari. Once the quota has been hit for an installed PWA, there doesn't appear to be any way to request additional storage.

In the past, if a site exceeded a certain threshold of data stored, the browser would prompt the user to grant permission to use more data. For example, if the origin used more than 50MB, the browser would prompt the user to allow it to store up to 100MB, then ask again at 50MB increments.

Today, most modern browsers will not prompt the user, and will allow a site to use up to its allotted quota. The exception appears to be Safari, which prompts when the storage quota is exceeded, requesting permission to increase the allocated quota. If an origin attempts to use more than its allotted quota, further attempts to write data will fail.

How can I check how much storage is available? #

In many browsers, you can use the StorageManager API to determine the amount of storage available to the origin, and how much storage it's using. It reports the total number of bytes used by IndexedDB and the Cache API, and makes it possible to calculate the approximate remaining storage space available.

if (navigator.storage && navigator.storage.estimate) {
  const quota = await navigator.storage.estimate();
  // quota.usage -> Number of bytes used.
  // quota.quota -> Maximum number of bytes available.
  const percentageUsed = (quota.usage / quota.quota) * 100;
  console.log(`You've used ${percentageUsed}% of the available storage.`);
  const remaining = quota.quota - quota.usage;
  console.log(`You can write up to ${remaining} more bytes.`);
}

The StorageManager isn't implemented in all browsers yet, so you must feature detect it before using it. Even when it is available, you must still catch over-quota errors (see below). In some cases, it's possible for the available quota to exceed the actual amount of storage available.

Inspect #

During development, you can use your browser's DevTools to inspect the different storage types, and easily clear all stored data.

A new feature was added in Chrome 88 that lets you override the site's storage quota in the Storage Pane. This feature gives you the ability to simulate different devices and test the behavior of your apps in low disk availability scenarios. Go to Application then Storage, enable the Simulate custom storage quota checkbox, and enter any valid number to simulate the storage quota.

While working on this article, I wrote a simple tool to attempt to quickly use as much storage as possible. It's a quick and easy way to experiment with different storage mechanisms, and see what happens when you use all of your quota.

How to handle going over quota? #

What should you do when you go over quota? Most importantly, you should always catch and handle write errors, whether it's a QuotaExceededError or something else. Then, depending on your app design, decide how to handle it. For example delete content that hasn't been accessed in a long time, remove data based on size, or provide a way for users to choose what they want to delete.

Both IndexedDB and the Cache API both throw a DOMError named QuotaExceededError when you've exceeded the quota available.

IndexedDB #

If the origin has exceeded its quota, attempts to write to IndexedDB will fail. The transaction's onabort() handler will be called, passing an event. The event will include a DOMException in the error property. Checking the error name will return QuotaExceededError.

const transaction = idb.transaction(['entries'], 'readwrite');
transaction.onabort = function(event) {
  const error = event.target.error; // DOMException
  if (error.name == 'QuotaExceededError') {
    // Fallback code goes here
  }
};

Cache API #

If the origin has exceeded its quota, attempts to write to the Cache API will reject with a QuotaExceededError DOMException.

try {
  const cache = await caches.open('my-cache');
  await cache.add(new Request('/sample1.jpg'));
} catch (err) {
  if (error.name === 'QuotaExceededError') {
    // Fallback code goes here
  }
}

How does eviction work? #

Web storage is categorized into two buckets, "Best Effort" and "Persistent". Best effort means the storage can be cleared by the browser without interrupting the user, but is less durable for long-term or critical data. Persistent storage is not automatically cleared when storage is low. The user needs to manually clear this storage (via browser settings).

By default, a site's data (including IndexedDB, Cache API, etc) falls into the best effort category, which means unless a site has requested persistent storage, the browser may evict site data at its discretion, for example, when device storage is low.

The eviction policy for best effort is:

Chromium-based browsers will begin to evict data when the browser runs out of space, clearing all site data from the least recently used origin first, then the next, until the browser is no longer over the limit.
Internet Explorer 10+ will not evict data, but will prevent the origin from writing any more.
Firefox will begin to evict data when the available disk space is filled up, clearing all site data from the least recently used origin first, then the next, until the browser is no longer over the limit.
Safari previously did not evict data, but recently implemented a new seven-day cap on all writable storage (see below).

Starting in iOS and iPadOS 13.4 and Safari 13.1 on macOS, there is a seven-day cap on all script writable storage, including IndexedDB, service worker registration, and the Cache API. This means Safari will evict all content from the cache after seven days of Safari use if the user does not interact with the site. This eviction policy does not apply to installed PWAs that have been added to the home screen. See Full Third-Party Cookie Blocking and More on the WebKit blog for complete details.

Bonus: Why use a wrapper for IndexedDB #

IndexedDB is a low level API that requires significant setup before use, which can be particularly painful for storing simple data. Unlike most modern promise-based APIs, it is event based. Promise wrappers like idb for IndexedDB hide some of the powerful features but more importantly, hide the complex machinery (e.g. transactions, schema versioning) that comes with the IndexedDB library.

Conclusion #

Gone are the days of limited storage and prompting the user to store more and more data. Sites can store effectively all of the resources and data they need to run. Using the StorageManager API you can determine how much is available to you, and how much you've used. And with persistent storage, unless the user removes it, you can protect it from eviction.

Additional resources #

Thanks #

Special thanks to Jarryd Goodman, Phil Walton, Eiji Kitamura, Daniel Murphy, Darwin Huang, Josh Bell, Marijn Kruisselbrink, and Victor Costan for reviewing this article. Thanks to Eiji Kitamura, Addy Osmani, and Marc Cohen who wrote the original articles that this is based on. Eiji wrote a helpful tool called Browser Storage Abuser that was useful in validating current behavior. It allows you to store as much data as possible and see the storage limits on your browser. Thanks to Francois Beaufort who did the digging into Safari to figure out its storage limits.

The hero image is by Guillaume Bolduc on Unsplash.

What does it take to be installable?

2020-02-14T00:00:00Z

Progressive Web Apps (PWAs) are modern, high quality applications built using web technology. PWAs offer similar capabilities to iOS/Android/desktop apps, they are reliable even in unstable network conditions, and are installable making it easier for users to find and use them.

Most users are familiar with installing applications, and the benefits of an installed experience. Installed applications appear on operating system launch surfaces, such as the Applications folder on Mac OS X, the Start menu on Windows, and the home screen on Android and iOS. Installed applications also show up in the activity switcher, device search engines such as Spotlight and in content sharing sheets.

Most browsers indicate to the user that your Progressive Web App (PWA) is installable when it meets certain criteria. Example indicators include an Install button in the address bar, or an Install menu item in the overflow menu.

Browser provided install promotion (mobile)

In addition, when the criteria is met, many browsers will fire a beforeinstallprompt event, allowing you to provide a custom in-app UX that that will trigger the install flow within your app.

Install criteria #

In Chrome, your Progressive Web App must meet the following criteria before it will fire the beforeinstallprompt event and show the in-browser install promotion:

The web app is not already installed
Meets the user engagement heuristics:
- The user needs to have clicked or tapped on the page at least once (at any time, even during a previous page load)
- The user needs to have spent at least 30 seconds viewing the page (at any time)
Be served over HTTPS
Includes a web app manifest that includes:
- short_name or name
- icons - must include a 192px and a 512px icon
- start_url
- display - must be one of fullscreen, standalone, or minimal-ui
- prefer_related_applications must not be present, or be false

Other browsers have similar criteria for installation, though there may be minor differences. Check the respective sites for full details:

How to provide your own in-app install experience

2020-02-14T00:00:00Z

Many browsers make it possible for you to enable and promote the installation of your Progressive Web App (PWA) directly within the user interface of your PWA. Installation (sometimes formerly referred to as Add to Home Screen), makes it easy for users to install your PWA on their mobile or desktop device. Installing a PWA adds it to a user's launcher, allowing it to be run like any other installed app.

In addition to the browser provided install experience, it's possible to provide your own custom install flow, directly within your app.

"Install App" button provided in the Spotify PWA

When considering whether to promote install, it's best to think about how users typically use your PWA. For example, if there's a set of users who use your PWA multiple times in a week, these users might benefit from the added convenience of launching your app from a smartphone homescreen or from the Start menu in a desktop operating system. Some productivity and entertainment applications also benefit from the extra screen real-estate created by removing the browser toolbars from the window in installed standalone or minimal-ui modes.

Promoting installation #

To indicate your Progressive Web App is installable, and to provide a custom in-app install flow:

Listen for the beforeinstallprompt event.
Save the beforeinstallprompt event, so it can be used to trigger the install flow later.
Alert the user that your PWA is installable, and provide a button or other element to start the in-app installation flow.

Listen for the `beforeinstallprompt` event #

If your Progressive Web App meets the required installation criteria, the browser fires a beforeinstallprompt event. Save a reference to the event, and update your user interface to indicate that the user can install your PWA. This is highlighted below.

// Initialize deferredPrompt for use later to show browser install prompt.
let deferredPrompt;

window.addEventListener('beforeinstallprompt', (e) => {
  // Prevent the mini-infobar from appearing on mobile
  e.preventDefault();
  // Stash the event so it can be triggered later.
  deferredPrompt = e;
  // Update UI notify the user they can install the PWA
  showInstallPromotion();
  // Optionally, send analytics event that PWA install promo was shown.
  console.log(`'beforeinstallprompt' event was fired.`);
});

In-app installation flow #

To provide in-app installation, provide a button or other interface element that a user can click to install your app. When the element is clicked, call prompt() on the saved beforeinstallprompt event (stored in the deferredPrompt variable). It shows the user a modal install dialog, asking them to confirm they want to install your PWA.

buttonInstall.addEventListener('click', async () => {
  // Hide the app provided install promotion
  hideInstallPromotion();
  // Show the install prompt
  deferredPrompt.prompt();
  // Wait for the user to respond to the prompt
  const { outcome } = await deferredPrompt.userChoice;
  // Optionally, send analytics event with outcome of user choice
  console.log(`User response to the install prompt: ${outcome}`);
  // We've used the prompt, and can't use it again, throw it away
  deferredPrompt = null;
});

The userChoice property is a promise that resolves with the user's choice. You can only call prompt() on the deferred event once. If the user dismisses it, you'll need to wait until the beforeinstallprompt event is fired again, typically immediately after the userChoice property has resolved.

Detect when the PWA was successfully installed #

You can use the userChoice property to determine if the user installed your app from within your user interface. But, if the user installs your PWA from the address bar or other browser component, userChoice won't help. Instead, you should listen for the appinstalled event. It is fired whenever your PWA is installed, no matter what mechanism is used to install your PWA.

window.addEventListener('appinstalled', () => {
  // Hide the app-provided install promotion
  hideInstallPromotion();
  // Clear the deferredPrompt so it can be garbage collected
  deferredPrompt = null;
  // Optionally, send analytics event to indicate successful install
  console.log('PWA was installed');
});

Detect how the PWA was launched #

The CSS display-mode media query indicates how the PWA was launched, either in a browser tab, or as an installed PWA. This makes it possible to apply different styles depending on how the app was launched. For example, always hide the install button and provide a back button when launched as an installed PWA.

Track how the PWA was launched #

To track how users launch your PWA, use matchMedia() to test the display-mode media query. Safari on iOS doesn't support this yet, so you must check navigator.standalone, it returns a boolean indicating whether the browser is running in standalone mode.

function getPWADisplayMode() {
  const isStandalone = window.matchMedia('(display-mode: standalone)').matches;
  if (document.referrer.startsWith('android-app://')) {
    return 'twa';
  } else if (navigator.standalone || isStandalone) {
    return 'standalone';
  }
  return 'browser';
}

Track when the display mode changes #

To track if the user changes between standalone, and browser tab, listen for changes to the display-mode media query.

window.matchMedia('(display-mode: standalone)').addEventListener('change', (evt) => {
  let displayMode = 'browser';
  if (evt.matches) {
    displayMode = 'standalone';
  }
  // Log display mode change to analytics
  console.log('DISPLAY_MODE_CHANGED', displayMode);
});

Update UI based on the current display mode #

To apply a different background color for a PWA when launched as an installed PWA, use conditional CSS:

@media all and (display-mode: standalone) {
  body {
    background-color: yellow;
  }
}

Updating your app's icon and name #

What if you need to update your app name, or provide new icons? Check out How Chrome handles updates to the web app manifest to see when and how are those changes are reflected in Chrome.

What makes a good Progressive Web App?

2020-01-06T00:00:00Z

Progressive Web Apps (PWA) are built and enhanced with modern APIs to deliver enhanced capabilities, reliability, and installability while reaching anyone, anywhere, on any device with a single codebase. To help you create the best possible experience, use the core and optimal checklists and recommendations to guide you.

Core Progressive Web App checklist #

The Progressive Web App Checklist describes what makes an app installable and usable by all users, regardless of size or input type.

Starts fast, stays fast

Performance plays a significant role in the success of any online experience, because high performing sites engage and retain users better than poorly performing ones. Sites should focus on optimizing for user-centric performance metrics.

Why #

Speed is critical for getting users to use your app. In fact, as page load times go from one second to ten seconds, the probability of a user bouncing increases by 123%. Performance doesn't stop with the load event. Users should never wonder whether their interaction—for example, clicking a button—was registered or not. Scrolling and animation should feel smooth. Performance affects your entire experience, from how users perceive your application to how it actually performs.

While all applications have different needs, the performance audits in Lighthouse are based on the Core Web Vitals, and scoring high on those audits will make it more likely that your users have an enjoyable experience. You can also use PageSpeed Insights or the Chrome User Experience Report to get real-world performance data for your web app.

How #

Follow our guide on fast load times to learn how to make your PWA start fast and stay fast.

Works in any browser

Users can use any browser they choose to access your web app before it's installed.

Why #

Progressive Web Apps are web apps first, and that means they need to work across browsers, not just in one of them.

An effective way of doing this is by, in the words of Jeremy Keith in Resilient Web Design, identifying the core functionality, making that functionality available using the simplest possible technology, and then enhancing the experience where possible. In many cases, this means starting with just HTML to create the core functionality, and enhancing the user experience with CSS and JavaScript to create a more engaging experience.

Take form submission for example. The simplest way to implement that is an HTML form that submits a POST request. After building that, you can enhance the experience with JavaScript to do form validation and submit the form via AJAX, improving the experience for users who can support it.

Consider that your users will experience your site across a spectrum of devices and browsers. You cannot simply target the top end of the spectrum. By using feature detection, you'll be able to deliver a usable experience for the widest range of potential users, including those using browsers and devices that may not exist today.

How #

Jeremy Keith's Resilient Web Design is an excellent resource describing how to think about web design in this cross-browser, progressive methodology.

Additional reading #

A List Apart's Understanding Progressive Enhancement is a good introduction to the topic.
Smashing Magazine's Progressive Enhancement: What It Is, And How To Use It? gives a practical introduction and links to more advanced topics.
MDN has an article titled Implementing feature detection that talks about how to detect a feature by directly querying it.

Responsive to any screen size

Users can use your PWA on any screen size and all of the content is available at any viewport size.

Why #

Devices come in a range of sizes, and users may use your application at a range of sizes, even on the same device. Therefore, it's critical to ensure your content not only fits within the viewport, but that all features and content for your site are usable at all viewport sizes.

The tasks users want to complete and the content they want to access do not change with viewport size. The content can be rearranged at different viewport sizes, and it should all be there, one way or another. In fact, as Luke Wroblewski states in his book Mobile First, starting small and going large instead of the other way around can actually improve a site's design:

Mobile devices require software development teams to focus on only the most important data and actions in an application. There simply isn't room in a 320 by 480 pixel screen for extraneous, unnecessary elements. You have to prioritize.

How #

There are many resources on responsive design, including the original article by Ethan Marcotte, a collection of important concepts related to it, as well as books and talks galore. To narrow this discussion down to the content aspects of responsive design, you can dig into content-first design and content-out responsive layouts. Finally, while it's focused on mobile, the lessons in Seven Deadly Mobile Myths by Josh Clark are just as relevant to small-sized views of responsive sites as they are to mobile.

Provides a custom offline page

When users are offline, keeping them in your PWA provides a more seamless experience than dropping back to the default browser offline page.

Why #

Users expect installed apps to work regardless of their connection status. A platform-specific app never shows a blank page when it is offline, and a Progressive Web App should never show the browser default offline page. Providing a custom offline experience, both when a user navigates to a URL that hasn't been cached and when a user tries to use a feature that requires a connection, helps your web experience feel like it's part of the device it's running on.

How #

During a service worker's install event, you can precache a custom offline page for later use. If a user goes offline, you can respond with the precached custom offline page. You can follow our custom offline page sample to see an example of this in action and learn how to implement it yourself.

Is installable

Users who install or add apps to their device tend to engage with those apps more.

There are a number of high-priority checks to ensure a healthy codebase: avoiding using libraries with known vulnerabilities, ensuring you're not using deprecated APIs, removing web anti-patterns from your codebase (like using document.write() or having non-passive scroll event listeners), and even coding defensively to ensure your PWA doesn't break if analytics or other third party libraries fail to load. Consider requiring static code analysis, like linting, as well as automated testing, in multiple browsers and release channels. These techniques can help catch errors before they make it into production.

What are Progressive Web Apps?

2020-01-06T00:00:00Z

The web is an incredible platform. Its mix of ubiquity across devices and operating systems, its user-centered security model, and the fact that neither its specification nor its implementation are controlled by a single company makes the web a unique platform to develop software on. Combined with its inherent linkability, it's possible to search it and share what you've found with anyone, anywhere. Whenever you go to a website, it's up-to-date, and your experience with that site can be as ephemeral or as permanent as you'd like. Web applications can reach anyone, anywhere, on any device with a single codebase.

Platform-specific applications are known for being incredibly rich and reliable. They're ever-present, on home screens, docks, and taskbars. They work regardless of network connection. They launch in their own standalone experience. They can read and write files from the local file system, access hardware connected via USB, serial port, or bluetooth, and even interact with data stored on your device, such as contacts and calendar events. In these applications, you can do things such as take pictures, see playing songs listed on the home screen, or control song playback while in another app. Platform-specific applications feel like part of the device they run on.

Capabilities vs. reach of platform-specific apps, web apps, and progressive web apps.

If you think about platform-specific apps and web apps in terms of capabilities and reach, platform-specific apps represent the best of capabilities whereas web apps represent the best of reach. So where do Progressive Web Apps fit in?

The three app pillars #

Progressive Web Apps are web applications that have been designed to be capable, reliable, and installable. These three pillars transform them into an experience that feels like a platform-specific application.

Capable #

The web is quite capable in its own right today. For example, you can build a hyper-local video chat app using WebRTC, geolocation, and push notifications. You can make that app installable and take its conversations virtual with WebGL and WebVR. With the introduction of WebAssembly, developers can tap into other ecosystems, such as C, C++, and Rust, and bring decades of work and capabilities to the web. Squoosh.app, for instance, uses this for its advanced image compression.

Until recently, only platform-specific apps could really lay claim to these capabilities. While some capabilities are still out of the web's reach, new and upcoming APIs are looking to change that, expanding what the web can do with features like file system access, media controls, app badging, and full clipboard support. All of these capabilities are built with the web's secure, user-centric permission model, ensuring that going to a website is never scary for users.

Between modern APIs, WebAssembly, and new and upcoming APIs, web applications are more capable than ever, and those capabilities are only growing.

Reliable #

A reliable Progressive Web App feels fast and dependable regardless of the network.

Speed is critical for getting users to use your experience. In fact, as page load times go from 1 second to ten seconds, the probability of a user bouncing increases by 123%. Performance doesn't stop after the onload event. Users should never wonder whether their interaction—for example, clicking a button—was registered or not. Scrolling and animation should feel smooth. Performance affects the entire user experience, from how they perceive your application to how it actually performs.

Finally, reliable applications need to be usable regardless of network connection. Users expect apps to start up on slow or flaky network connections or even when offline. They expect the most recent content they've interacted with, such as media tracks or tickets and itineraries, to be available and usable even if getting a request to your server is hard. When a request isn't possible, they expect to be told there's trouble instead of silently failing or crashing.

Users deserve apps that respond to interaction in the blink of an eye, and an experience they can depend on.

Installable #

Installed Progressive Web Apps run in a standalone window instead of a browser tab. They're launchable from on the user's home screen, dock, taskbar, or shelf. It's possible to search for them on a device and jump between them with the app switcher, making them feel like part of the device they're installed on.

New capabilities open up after a web app is installed. Keyboard shortcuts, usually reserved when running in the browser, become available. Progressive Web Apps can register to accept content from other applications, or to be the default application to handle different types of files.

When a Progressive Web App moves out of a tab and into a standalone app window, it transforms how users think about it and interact with it.

The best of both worlds #

At their heart, Progressive Web Apps are just web applications. Using progressive enhancement, new capabilities are enabled in modern browsers. Using service workers and a web app manifest, your web application becomes reliable and installable. If the new capabilities aren't available, users still get the core experience.

The numbers don't lie! Companies that have launched Progressive Web Apps have seen impressive results. For example, Twitter saw a 65% increase in pages per session, 75% more Tweets, and a 20% decrease in bounce rate, all while reducing the size of their app by over 97%. After switching to a PWA, Nikkei saw 2.3 times more organic traffic, 58% more subscriptions, and 49% more daily active users. Hulu replaced their platform-specific desktop experience with a Progressive Web App and saw a 27% increase in return visits.

Progressive Web Apps provide you with a unique opportunity to deliver a web experience your users will love. Using the latest web features to bring enhanced capabilities and reliability, Progressive Web Apps allow what you build to be installed by anyone, anywhere, on any device with a single codebase.

Address Bar Install for Progressive Web Apps on the Desktop

2019-06-12T00:00:00Z

On desktop, there's typically no indication to a user that a Progressive Web App is installable, and if it is, the install flow is hidden within the three dot menu.

In Chrome 76 (beta mid-June 2019), we're making it easier for users to install Progressive Web Apps on the desktop by adding an install button to the address bar (omnibox). If a site meets the Progressive Web App installability criteria, Chrome will automatically show an install icon in the address bar. Clicking the button prompts the user to install the PWA.

Like other install events, you can listen for the appinstalled event to detect if the user installed your PWA.

Adding your own install prompt #

If your PWA has use cases where it’s helpful for a user to install your app, for example if you have users who use your app more than once a week, you should be promoting the installation of your PWA within the web UI of your app.

To add your own custom install button, listen for the beforeinstallprompt event. When it’s fired, save a reference to the event, and update your user interface to let the user know they can install your Progressive Web App.

Patterns for promoting the installation of your PWA #

There are three key ways you can promote the installation of your PWA:

Automatic browser promotion, like the address bar install button.
Application UI promotion, where UI elements appear in the application interface, such as banners, buttons in the header or navigation menu, etc.
Inline promotional patterns interweave promotions within the site content.

Check out Patterns for Promoting PWA Installation (mobile) for more details. Its focus is mobile, but many of the patterns are applicable for desktop, or can be easily modified to work for desktop experiences.

How do I notify users that my PWA is installable?

2019-06-04T00:00:00Z

But how should you notify the user that your PWA can be installed?

Check out Patterns for Promoting PWA Installation, a series of recommended patterns and best practices that you can use to promote the installation of your Progressive Web App.

It includes patterns for notifying users within the core UI of your app, within your app's content, or just letting the browser notify the user. And, it includes recommendations on how to place the notification for different types of apps.

Responsive web design basics

2019-02-12T00:00:00Z

The use of mobile devices to surf the web continues to grow at an astronomical pace, and these devices are often constrained by display size and require a different approach to how content is laid out on the screen.

Responsive web design, originally defined by Ethan Marcotte in A List Apart, responds to the needs of the users and the devices they're using. The layout changes based on the size and capabilities of the device. For example, on a phone users would see content shown in a single column view; a tablet might show the same content in two columns.

In this video the design moves from a narrow to a wide viewport, responding to the available screen real estate.

A multitude of different screen sizes exist across phones, "phablets," tablets, desktops, game consoles, TVs, and even wearables. Screen sizes are always changing, so it's important that your site can adapt to any screen size, today or in the future. In addition, devices have different features with which we interact with them. For example some of your visitors will be using a touchscreen. Modern responsive design considers all of these things to optimize the experience for everyone.

Set the viewport #

Pages optimized for a variety of devices must include a meta viewport tag in the head of the document. A meta viewport tag gives the browser instructions on how to control the page's dimensions and scaling.

To attempt to provide the best experience, mobile browsers render the page at a desktop screen width (usually about 980px, though this varies across devices), and then try to make the content look better by increasing font sizes and scaling the content to fit the screen. This means that font sizes may appear inconsistent to users, who may have to double-tap or pinch-to-zoom in order to see and interact with the content.

<!DOCTYPE html>
<html lang="en">
  <head>
    …
    <meta name="viewport" content="width=device-width, initial-scale=1">
    …
  </head>
  …

Using the meta viewport value width=device-width instructs the page to match the screen's width in device-independent pixels. A device (or density) independent pixel being a representation of a single pixel, which may on a high density screen consist of many physical pixels. This allows the page to reflow content to match different screen sizes, whether rendered on a small mobile phone or a large desktop monitor.

An example of how the page loads in a device without the viewport meta tag. See this example on Glitch.

An example of how the page loads in a device with the viewport meta tag. See this example on Glitch.

Some browsers keep the page's width constant when rotating to landscape mode, and zoom rather than reflow to fill the screen. Adding the value initial-scale=1 instructs browsers to establish a 1:1 relationship between CSS pixels and device-independent pixels regardless of device orientation, and allows the page to take advantage of the full landscape width.

The Does not have a <meta name="viewport"> tag with width or initial-scale Lighthouse audit can help you automate the process of making sure that your HTML documents are using the viewport meta tag correctly.

Ensure an accessible viewport #

In addition to setting an initial-scale, you can also set the following attributes on the viewport:

minimum-scale
maximum-scale
user-scalable

When set, these can disable the user's ability to zoom the viewport, potentially causing accessibility issues. Therefore we would not recommend using these attributes.

Size content to the viewport #

On both desktop and mobile devices, users are used to scrolling websites vertically but not horizontally; forcing the user to scroll horizontally or to zoom out in order to see the whole page results in a poor user experience.

When developing a mobile site with a meta viewport tag, it's easy to accidentally create page content that doesn't quite fit within the specified viewport. For example, an image that is displayed at a width wider than the viewport can cause the viewport to scroll horizontally. You should adjust this content to fit within the width of the viewport, so that the user does not need to scroll horizontally.

The Content is not sized correctly for the viewport Lighthouse audit can help you automate the process of detecting overflowing content.

Images #

An image has fixed dimensions and if it is larger than the viewport will cause a scrollbar. A common way to deal with this problem is to give all images a max-width of 100%. This will cause the image to shrink to fit the space it has, should the viewport size be smaller than the image. However because the max-width, rather than the width is 100%, the image will not stretch larger than its natural size. It is generally safe to add the following to your stylesheet so that you will never have a problem with images causing a scrollbar.

img {
  max-width: 100%;
  display: block;
}

Add the dimensions of the image to the img element #

When using max-width: 100% you are overriding the natural dimensions of the image, however you should still use the width and height attributes on your <img> tag. This is because modern browsers will use this information to reserve space for the image before it loads in, this will help to avoid layout shifts as content loads.

Layout #

Since screen dimensions and width in CSS pixels vary widely between devices (for example, between phones and tablets, and even between different phones), content should not rely on a particular viewport width to render well.

In the past, this required setting elements used to create layout in percentages. In the example below, you can see a two-column layout with floated elements, sized using pixels. Once the viewport becomes smaller than the total width of the columns, we have to scroll horizontally to see the content.

A floated layout using pixels. See this example on Glitch.

By using percentages for the widths, the columns always remain a certain percentage of the container. This means that the columns become narrower, rather than creating a scrollbar.

Modern CSS layout techniques such as Flexbox, Grid Layout, and Multicol make the creation of these flexible grids much easier.

Flexbox #

This layout method is ideal when you have a set of items of different sizes and you would like them to fit comfortably in a row or rows, with smaller items taking less space and larger ones getting more space.

.items {
  display: flex;
  justify-content: space-between;
}

In a responsive design, you can use Flexbox to display items as a single row, or wrapped onto multiple rows as the available space decreases.

CSS Grid Layout #

CSS Grid Layout allows for the straightforward creation of flexible grids. If we consider the earlier floated example, rather than creating our columns with percentages, we could use grid layout and the fr unit, which represents a portion of the available space in the container.

.container {
  display: grid;
  grid-template-columns: 1fr 3fr;
}

Grid can also be used to create regular grid layouts, with as many items as will fit. The number of available tracks will be reduced as the screen size shrinks. In the below demo, we have as many cards as will fit on each row, with a minimum size of 200px.

Multiple-column layout #

For some types of layout you can use Multiple-column Layout (Multicol), which can create responsive numbers of columns with the column-width property. In the demo below, you can see that columns are added if there is room for another 200px column.

Use CSS media queries for responsiveness #

Sometimes you will need to make more extensive changes to your layout to support a certain screen size than the techniques shown above will allow. This is where media queries become useful.

Media queries are simple filters that can be applied to CSS styles. They make it easy to change styles based on the types of device rendering the content, or the features of that device, for example width, height, orientation, ability to hover, and whether the device is being used as a touchscreen.

To provide different styles for printing, you need to target a type of output so you could include a stylesheet with print styles as follows:

<!DOCTYPE html>
<html lang="en">
  <head>
    …
    <link rel="stylesheet" href="print.css" media="print">
    …
  </head>
  …

Alternatively, you could include print styles within your main stylesheet using a media query:

@media print {
  /* print styles go here */
}

For responsive web design, we are typically querying the features of the device in order to provide a different layout for smaller screens, or when we detect that our visitor is using a touchscreen.

Media queries based on viewport size #

Media queries enable us to create a responsive experience where specific styles are applied to small screens, large screens, and anywhere in between. The feature we are detecting here is therefore screen size, and we can test for the following things.

width (min-width, max-width)
height (min-height, max-height)
orientation
aspect-ratio

All of these features have excellent browser support, for more details including browser support information see width, height, orientation, and aspect-ratio on MDN.

Media queries based on device capability #

Given the range of devices available, we cannot make the assumption that every large device is a regular desktop or laptop computer, or that people are only using a touchscreen on a small device. With some newer additions to the media queries specification we can test for features such as the type of pointer used to interact with the device and whether the user can hover over elements.

hover
pointer
any-hover
any-pointer

Try viewing this demo on different devices, such as a regular desktop computer and a phone or tablet.

These newer features have good support in all modern browsers. Find out more on the MDN pages for hover, any-hover, pointer, any-pointer.

Using `any-hover` and `any-pointer` #

The features any-hover and any-pointer test if the user has the capability to hover, or use that type of pointer even if it is not the primary way they are interacting with their device. Be very careful when using these. Forcing a user to switch to a mouse when they are using their touchscreen is not very friendly! However, any-hover and any-pointer may be useful if it is important to work out what kind of device a user has. For example, a laptop with a touchscreen and trackpad should match coarse and fine pointers, in addition to the ability to hover.

How to choose breakpoints #

Don't define breakpoints based on device classes. Defining breakpoints based on specific devices, products, brand names, or operating systems that are in use today can result in a maintenance nightmare. Instead, the content itself should determine how the layout adjusts to its container.

Pick major breakpoints by starting small, then working up #

Design the content to fit on a small screen size first, then expand the screen until a breakpoint becomes necessary. This allows you to optimize breakpoints based on content and maintain the least number of breakpoints possible.

Let's work through the example we saw at the beginning: the weather forecast. The first step is to make the forecast look good on a small screen.

The app at a narrow width.

Next, resize the browser until there is too much white space between the elements, and the forecast simply doesn't look as good. The decision is somewhat subjective, but above 600px is certainly too wide.

The app at a point where we feel we should tweak the design.

To insert a breakpoint at 600px, create two media queries at the end of your CSS for the component, one to use when the browser is 600px and below, and one for when it is wider than 600px.

@media (max-width: 600px) {

}

@media (min-width: 601px) {

}

Finally, refactor the CSS. Inside the media query for a max-width of 600px, add the CSS which is only for small screens. Inside the media query for a min-width of 601px add CSS for larger screens.

Pick minor breakpoints when necessary #

In addition to choosing major breakpoints when layout changes significantly, it is also helpful to adjust for minor changes. For example, between major breakpoints it may be helpful to adjust the margins or padding on an element, or increase the font size to make it feel more natural in the layout.

Let's start by optimizing the small screen layout. In this case, let's boost the font when the viewport width is greater than 360px. Second, when there is enough space, we can separate the high and low temperatures so that they're on the same line instead of on top of each other. And let's also make the weather icons a bit larger.

@media (min-width: 360px) {
  body {
    font-size: 1.0em;
  }
}

@media (min-width: 500px) {
  .seven-day-fc .temp-low,
  .seven-day-fc .temp-high {
    display: inline-block;
    width: 45%;
  }

  .seven-day-fc .seven-day-temp {
    margin-left: 5%;
  }

  .seven-day-fc .icon {
    width: 64px;
    height: 64px;
  }
}

Similarly, for the large screens it's best to limit to maximum width of the forecast panel so it doesn't consume the whole screen width.

@media (min-width: 700px) {
  .weather-forecast {
    width: 700px;
  }
}

Optimize text for reading #

Classic readability theory suggests that an ideal column should contain 70 to 80 characters per line (about 8 to 10 words in English). Thus, each time the width of a text block grows past about 10 words, consider adding a breakpoint.

The text as read on a mobile device.

The text as read on a desktop browser with a breakpoint added to constrain the line length.

Let's take a deeper look at the above blog post example. On smaller screens, the Roboto font at 1em works perfectly giving 10 words per line, but larger screens require a breakpoint. In this case, if the browser width is greater than 575px, the ideal content width is 550px.

@media (min-width: 575px) {
  article {
    width: 550px;
    margin-left: auto;
    margin-right: auto;
  }
}

Avoid simply hiding content #

Be careful when choosing what content to hide or show depending on screen size. Don't simply hide content just because you can't fit it on the screen. Screen size is not a definitive indication of what a user may want. For example, eliminating the pollen count from the weather forecast could be a serious issue for spring-time allergy sufferers who need the information to determine if they can go outside or not.

View media query breakpoints in Chrome DevTools #

Once you've got your media query breakpoints set up, you'll want to see how your site looks with them. You could resize your browser window to trigger the breakpoints, but Chrome DevTools has a built-in feature that makes it easy to see how a page looks under different breakpoints.

DevTools showing the weather app as it looks at a wider viewport size.

DevTools showing the weather app as it looks at a narrower viewport size.

To view your page under different breakpoints:

Open DevTools and then turn on Device Mode. This opens in responsive mode by default.

To see your media queries, open the Device Mode menu and select Show media queries to display your breakpoints as colored bars above your page.

Click on one of the bars to view your page while that media query is active. Right-click on a bar to jump to the media query's definition.

Is your app installed? getInstalledRelatedApps() will tell you!

2018-12-20T00:00:00Z

What is the getInstalledRelatedApps() API? #

A website using getInstalledRelatedApps() to determine if its Android app is already installed.

The getInstalledRelatedApps() makes it possible for your page to check if your mobile or desktop app, or in some cases, if your Progressive Web App (PWA) is already installed on a user's device, and allows you to customize the user experience if it is.

For example, if your app is already installed:

Redirecting the user from a product marketing page directly into your app.
Centralizing some functionality like notifications in the other app to prevent duplicate notifications.
Not promoting the installation of your PWA if your other app is already installed.

To use the getInstalledRelatedApps() API, you need to tell your app about your site, then tell your site about your app. Once you've defined the relationship between the two, you can check if the app is installed.

Supported app types you can check #

App type	Checkable from
Android app	Android only Chrome 80 or later
Windows (UWP) app	Windows only Chrome 85 or later Edge 85 or later
Progressive Web App Installed in the same scope or a different scope.	Android only Chrome 84 or later

Check if your Android app is installed #

Your website can check if your Android app is installed.

Supported on

Android: Chrome 80 or later

Tell your Android app about your website #

First, you'll need to update your Android app to define the relationship between your website and Android application using the Digital Asset Links system. This ensures that only your website can check if your Android app is installed.

In the AndroidManifest.xml of your Android app, add an asset_statements entry:

<manifest>
  <application>
   …
    <meta-data android:name="asset_statements" android:resource="@string/asset_statements" />
   …
  </application>
</manifest>

Then, in strings.xml, add the following asset statement, updating site with your domain. Be sure to include the escaping characters.

<string name="asset_statements">
  [{
    \"relation\": [\"delegate_permission/common.handle_all_urls\"],
    \"target\": {
      \"namespace\": \"web\",
      \"site\": \"https://example.com\"
    }
  }]
</string>

Once completed, publish your updated Android app to the Play store.

Tell your website about your Android app #

Next, tell your website about your Android app by adding a web app manifest to your page. The manifest must include the related_applications property, an array that provides the details about your app, including platform and id.

platform must be play
id is the GooglePlay application ID for your Android app

{
  "related_applications": [{
    "platform": "play",
    "id": "com.android.chrome",
  }]
}

Check if your app is installed #

Finally, call navigator.getInstalledRelatedApps() to check if your Android app is installed.

Try the demo

Check if your Windows (UWP) app is installed #

Your website can check if your Windows app (built using UWP) is installed.

Supported on

Windows: Chrome 85 or later, Edge 85 or later

Tell your Windows app about your website #

You'll need to update your Windows app to define the relationship between your website and Windows application using URI Handlers. This ensures that only your website can check if your Windows app is installed.

Add the Windows.appUriHandler extension registration to your app's manifest file Package.appxmanifest. For example, if your website's address is example.com you would add the following entry in your app's manifest:

<Applications>
  <Application Id="App" ... >
      ...
      <Extensions>
         <uap3:Extension Category="windows.appUriHandler">
          <uap3:AppUriHandler>
            <uap3:Host Name="example.com" />
          </uap3:AppUriHandler>
        </uap3:Extension>
      </Extensions>
  </Application>
</Applications>

Note, you may need to add the uap3 namespace to your <Package> attribute.

Then, create a JSON file (without the .json file extension) named windows-app-web-link and provide your app's package family name. Place that file either on your server root, or in the /.well-known/ directory. You can find the package family name in the Packaging section in the app manifest designer.

[{
  "packageFamilyName": "MyApp_9jmtgj1pbbz6e",
  "paths": [ "*" ]
}]

See Enable apps for websites using app URI handlers for complete details on setting up URI handlers.

Tell your website about your Windows app #

Next, tell your website about your Windows app by adding a web app manifest to your page. The manifest must include related_applications property, an array that provides the details about your app, including platform and id.

platform must be windows
id is your app's package family name, appended by the <Application> Id value in your Package.appxmanifest file.

{
  "related_applications": [{
    "platform": "windows",
    "id": "MyApp_9jmtgj1pbbz6e!App",
  }]
}

Check if your app is installed #

Finally, call navigator.getInstalledRelatedApps() to check if your Windows app is installed.

Check if your Progressive Web App is already installed (in scope) #

Your PWA can check to see if it is already installed. In this case, the page making the request must be on the same domain, and within the scope of your PWA, as defined by the scope in the web app manifest.

Supported on

Android: Chrome 84 or later

Tell your PWA about itself #

Tell your PWA about itself by adding a related_applications entry in your PWAs web app manifest.

platform must be webapp
url is the full path to the web app manifest of your PWA

{
  …
  "scope": "/",
  "start_url": "/",
  "related_applications": [{
    "platform": "webapp",
    "url": "https://example.com/manifest.json",
  }],
  …
}

Check if your PWA is installed #

Finally, call navigator.getInstalledRelatedApps() from within the scope of your PWA to check if it is installed. If getInstalledRelatedApps() is called outside the scope of your PWA, it will return false. See the next section for details.

Try the demo

Check if your Progressive Web App is installed (out of scope) #

Your website can check if your PWA is installed, even if the page is outside the scope of your PWA. For example, a landing page served from /landing/ can check if the PWA served from /pwa/ is installed, or if your landing page is served from www.example.com and your PWA is served from app.example.com.

Supported on

Android: Chrome 84 or later

Tell your PWA about your website #

First, you'll need to add digital asset links to the server where your PWA is served from. This will help define the relationship between your website and your PWA, and ensures that only your website can check if your PWA is installed.

Add an assetlinks.json file to the /.well-known/ directory of the domain where the PWA lives, for example app.example.com. In the site property, provide the full path to the web app manifest that will perform the check (not the web app manifest of your PWA).

// Served from https://app.example.com/.well-known/assetlinks.json
[
  {
    "relation": ["delegate_permission/common.query_webapk"],
    "target": {
      "namespace": "web",
      "site": "https://www.example.com/manifest.json"
    }
  }
]

Tell your website about your PWA #

Next, tell your website about your PWA app by adding a web app manifest to your page. The manifest must include the related_applications property, an array that provides the details about your PWA, including platform and url.

platform must be webapp
url is the full path to the web app manifest of your PWA

{
  "related_applications": [{
    "platform": "webapp",
    "url": "https://app.example.com/manifest.json",
  }]
}

Check if your PWA is installed #

Finally, call navigator.getInstalledRelatedApps() to check if your PWA is installed.

Try the demo

Calling getInstalledRelatedApps() #

Calling navigator.getInstalledRelatedApps() returns a promise that resolves with an array of your apps that are installed on the user's device.

const relatedApps = await navigator.getInstalledRelatedApps();
relatedApps.forEach((app) => {
  console.log(app.id, app.platform, app.url);
});

To prevent sites from testing an overly broad set of their own apps, only the first three apps declared in the web app manifest will be taken into account.

Like most other powerful web APIs, the getInstalledRelatedApps() API is only available when served over HTTPS.

Still have questions? #

Still have questions? Check the getInstalledRelatedApps tag on StackOverflow to see if anyone else has had similar questions. If not, ask your question there, and be sure to tag it with the progressive-web-apps tag. Our team frequently monitors that tag and tries to answer your questions.

Feedback #

Did you find a bug with Chrome's implementation? Or is the implementation different from the spec?

File a bug at https://new.crbug.com. Include as much detail as you can, provide simple instructions for reproducing the bug, and enter Mobile>WebAPKs in the Components box. Glitch works great for sharing quick and easy repros.

Show support for the API #

Are you planning to use the getInstalledRelatedApps() API? Your public support helps the Chrome team to prioritize features and shows other browser vendors how critical it is to support them.

Share how you plan to use the API on the WICG Discourse thread.
Send a tweet to @ChromiumDev using the hashtag #getInstalledRelatedApps and let us know where and how you're using it.

Helpful links #

Public explainer for getInstalledRelatedApps() API
Spec draft
Tracking bug
ChromeStatus.com entry
Blink Component: Mobile>WebAPKs

Thanks #

Special thanks to Sunggook Chue at Microsoft for helping with the details for testing Windows apps, and Rayan Kanso for help with the Chrome details.

Make it installable

2018-11-05T00:00:00Z

This glitch contains the web manifest with the required fields to make a Web App installable.

It also has an install button that is hidden by default.

Listen for the beforeinstallprompt event #

When the browser fires the beforeinstallprompt event, that's the indication that the Web App can be installed and an install button can be shown to the user. The beforeinstallprompt event is fired when the app meets the installability criteria.

Capturing the event enables developers to customize the installation and prompt the user to install when they consider it is the best time.

Click Remix to Edit to make the project editable.
Add a beforeinstallprompt event handler to the window object.
Save the event as a global variable; we'll need it later to show the prompt.
Unhide the install button.

Code:

window.addEventListener('beforeinstallprompt', (event) => {
  // Prevent the mini-infobar from appearing on mobile.
  event.preventDefault();
  console.log('👍', 'beforeinstallprompt', event);
  // Stash the event so it can be triggered later.
  window.deferredPrompt = event;
  // Remove the 'hidden' class from the install button container.
  divInstall.classList.toggle('hidden', false);
});

Handle the install button click #

To show the install prompt, call prompt() on the saved beforeinstallprompt event. Calling prompt() is done in the install button click handler because prompt() must be called from a user gesture.

Add a click event handler for the install button.
Call prompt() on the saved beforeinstallprompt event.
Log the results of the prompt.
Set the saved beforeinstallprompt event to null.
Hide the install button.

Code:

butInstall.addEventListener('click', async () => {
  console.log('👍', 'butInstall-clicked');
  const promptEvent = window.deferredPrompt;
  if (!promptEvent) {
    // The deferred prompt isn't available.
    return;
  }
  // Show the install prompt.
  promptEvent.prompt();
  // Log the result
  const result = await promptEvent.userChoice;
  console.log('👍', 'userChoice', result);
  // Reset the deferred prompt variable, since
  // prompt() can only be called once.
  window.deferredPrompt = null;
  // Hide the install button.
  divInstall.classList.toggle('hidden', true);
});

Track the install event #

Installing a Web App through an install button is only one way users can install it. They can also use Chrome's menu, the mini-infobar, and through an icon in the omnibox. You can track all of these ways of installation by listening for the appinstalled event.

Add an appinstalled event handler to the window object.
Log the install event to analytics or other mechanism.

Code:

window.addEventListener('appinstalled', (event) => {
  console.log('👍', 'appinstalled', event);
  // Clear the deferredPrompt so it can be garbage collected
  window.deferredPrompt = null;
});

Add a web app manifest

2018-11-05T00:00:00Z

The web app manifest is a JSON file that tells the browser about your Progressive Web App and how it should behave when installed on the user's desktop or mobile device. A typical manifest file includes the app name, the icons the app should use, and the URL that should be opened when the app is launched, among other things.

Browser support

Chrome 39, Supported 39
Firefox, Not supported
Edge 79, Supported 79
Safari, Not supported

Source

Create the manifest file #

The manifest file can have any name, but is commonly named manifest.json and served from the root (your website's top-level directory). The specification suggests the extension should be .webmanifest, but browsers also support .json extensions, which may be easier for developers to understand.

A typical manifest looks something like this:

{
  "short_name": "Weather",
  "name": "Weather: Do I need an umbrella?",
  "icons": [
    {
      "src": "/images/icons-vector.svg",
      "type": "image/svg+xml",
      "sizes": "512x512"
    },
    {
      "src": "/images/icons-192.png",
      "type": "image/png",
      "sizes": "192x192"
    },
    {
      "src": "/images/icons-512.png",
      "type": "image/png",
      "sizes": "512x512"
    }
  ],
  "id": "/?source=pwa",
  "start_url": "/?source=pwa",
  "background_color": "#3367D6",
  "display": "standalone",
  "scope": "/",
  "theme_color": "#3367D6",
  "shortcuts": [
    {
      "name": "How's weather today?",
      "short_name": "Today",
      "description": "View weather information for today",
      "url": "/today?source=pwa",
      "icons": [{ "src": "/images/today.png", "sizes": "192x192" }]
    },
    {
      "name": "How's weather tomorrow?",
      "short_name": "Tomorrow",
      "description": "View weather information for tomorrow",
      "url": "/tomorrow?source=pwa",
      "icons": [{ "src": "/images/tomorrow.png", "sizes": "192x192" }]
    }
  ],
  "description": "Weather forecast information",
  "screenshots": [
    {
      "src": "/images/screenshot1.png",
      "type": "image/png",
      "sizes": "540x720",
      "form_factor": "narrow"
    },
    {
      "src": "/images/screenshot2.jpg",
      "type": "image/jpg",
      "sizes": "720x540",
      "form_factor": "wide"
    }
  ]
}

Key manifest properties #

`short_name` and/or `name` #

You must provide at least the short_name or name property. If both are provided, short_name is used on the user's home screen, launcher, or other places where space may be limited. name is used when the app is installed.

`icons` #

When a user installs your PWA, you can define a set of icons for the browser to use on the home screen, app launcher, task switcher, splash screen, and so on.

The icons property is an array of image objects. Each object must include the src, a sizes property, and the type of image. To use maskable icons, sometimes referred to as adaptive icons on Android, you'll also need to add "purpose": "any maskable" to the icon property.

For Chromium, you must provide at least a 192x192 pixel icon, and a 512x512 pixel icon. If only those two icon sizes are provided, Chrome automatically scales the icons to fit the device. If you'd prefer to scale your own icons, and adjust them for pixel-perfection, provide icons in increments of 48dp.

`id` #

The id property allows you to explicitly define the identifier used for your application. Adding the id property to the manifest removes the dependency on the start_url or the location of the manifest, and makes it possible for them to be updated in the future. For more information, see Uniquely identifying PWAs with the web app manifest id property.

`start_url` #

The start_url is required and tells the browser where your application should start when it is launched, and prevents the app from starting on whatever page the user was on when they added your app to their home screen.

Your start_url should direct the user straight into your app, rather than a product landing page. Think about what the user will want to do once they open your app, and place them there.

`background_color` #

The background_color property is used on the splash screen when the application is first launched on mobile.

`display` #

You can customize what browser UI is shown when your app is launched. For example, you can hide the address bar and browser user interface elements. Games can even be made to launch full screen. The display property takes one of the following values:

Property	Use
`fullscreen`	Opens the web application without any browser UI and takes up the entirety of the available display area.
`standalone`	Opens the web app to look and feel like a standalone app. The app runs in its own window, separate from the browser, and hides standard browser UI elements such as the URL bar.
`minimal-ui`	This mode is similar to `standalone`, but provides the user a minimal set of UI elements for controlling navigation (such as back and reload).
`browser`	A standard browser experience.

`display_override` #

Web apps can choose how they are displayed by setting a display mode in their manifest as explained above. Browsers are not required to support all display modes, but they are required to support the spec-defined fallback chain ("fullscreen" → "standalone" → "minimal-ui" → "browser"). If they don't support a given mode, they fall back to the next display mode in the chain. This inflexible behavior can be problematic in rare cases. For example, a developer cannot request "minimal-ui" without being forced back into the "browser" display mode when "minimal-ui" is not supported. Another problem is that the current behavior makes it impossible to introduce new display modes in a backward compatible way, since explorations like tabbed application mode don't have a natural place in the fallback chain.

These problems are solved by the display_override property, which the browser considers before the display property. Its value is a sequence of strings that are considered in the listed order, and the first supported display mode is applied. If none are supported, the browser falls back to evaluating the display field.

Consider the example below. (The details of "window-control-overlay" are out-of-scope for this article.)

{
  "display_override": ["window-control-overlay", "minimal-ui"],
  "display": "standalone",
}

As stated, the browser will look at display_override first.

"window-control-overlay"
"minimal-ui"

If neither option is available, it falls back to display. If "standalone" is not available, it resumes spec-defined fallabck chain from that point.

"standalone"
"minimal-ui"
"browser"

`scope` #

The scope defines the set of URLs that the browser considers to be within your app, and is used to decide when the user has left the app. The scope controls the URL structure that encompasses all the entry and exit points in your web app. Your start_url must reside within the scope.

A few other notes on scope:

If you don't include a scope in your manifest, then the default implied scope is the directory that your web app manifest is served from.
The scope attribute can be a relative path (../), or any higher level path (/) which would allow for an increase in coverage of navigations in your web app.
The start_url must be in the scope.
The start_url is relative to the path defined in the scope attribute.
A start_url starting with / will always be the root of the origin.

`theme_color` #

The theme_color sets the color of the tool bar, and may be reflected in the app's preview in task switchers. The theme_color should match the meta theme color specified in your document head.

An example of a PWA window with custom theme_color.

As of Chromium 93 and Safari 15, you can adjust this color in a media query with the media attribute of the meta theme color element. The first one that matches will be picked. For example, you could have one color for light mode and another one for dark mode. At the time of writing, you can't define those in your manifest. See w3c/manifest#975 GitHub issue.

<meta name="theme-color" media="(prefers-color-scheme: light)" content="white">
<meta name="theme-color" media="(prefers-color-scheme: dark)"  content="black">

`shortcuts` #

The shortcuts property is an array of app shortcut objects whose goal is to provide quick access to key tasks within your app. Each member is a dictionary that contains at least a name and a url.

`description` #

The description property describes the purpose of your app.

`screenshots` #

The screenshots property is an array of image objects representing your app in common usage scenarios. Each object must include the src, a sizes property, and the type of image. The form_factor property is optional. You can set it either to "wide" for screenshots applicable to wide screens only or "narrow" for narrow screenshots. You should only use it when the layout varies by screen size.

In Chrome, the image must respond to certain criteria:

Width and height must be at least 320px and at most 3840px.
The maximum dimension can't be more than 2.3 times as long as the minimum dimension.
All screenshots matching the appropriate form factor must have the same aspect ratio.

Richer installation UI on desktop and mobile.

Add the web app manifest to your pages #

After creating the manifest, add a <link> tag to all the pages of your Progressive Web App. For example:

<link rel="manifest" href="/manifest.json">

Test your manifest #

To verify your manifest is setup correctly, use the Manifest pane in the Application panel of Chrome DevTools.

Test your manifest in DevTools.

This pane provides a human-readable version of many of your manifest's properties, and makes it easy to verify that all of the images are loading properly.

Splash screens on mobile #

When your app first launches on mobile, it can take a moment for the browser to spin up, and the initial content to begin rendering. Instead of showing a white screen that may look to the user like the app is stalled, the browser will show a splash screen until the first paint.

Chrome automatically creates the splash screen from the manifest properties, specifically:

name
background_color
icons

The background_color should be the same color as the load page, to provide a smooth transition from the splash screen to your app.

Chrome will choose the icon that closely matches the device resolution for the device. Providing 192px and 512px icons is sufficient for most cases, but you can provide additional icons for pixel perfection.

The Cache API: A quick guide

2017-10-03T00:00:00Z

The Cache API is a system for storing and retrieving network requests and their corresponding responses. These might be regular requests and responses created in the course of running your application, or they could be created solely for the purpose of storing data for later use.

The Cache API was created to enable service workers to cache network requests so that they can provide fast responses, regardless of network speed or availability. However, the API can also be used as a general storage mechanism.

Where is it available? #

The Cache API is available in all modern browsers. It is exposed via the global caches property, so you can test for the presence of the API with a simple feature detection:

const cacheAvailable = 'caches' in self;

Browser support

Chrome 40, Supported 40
Firefox 41, Supported 41
Edge 16, Supported 16
Safari 11.1, Supported 11.1

Source

The Cache API can be accessed from a window, iframe, worker, or service worker.

What can be stored #

The caches only store pairs of Request and Response objects, representing HTTP requests and responses, respectively. However, the requests and responses can contain any kind of data that can be transferred over HTTP.

How much can be stored? #

Creating and opening a cache #

To open a cache, use the caches.open(name) method, passing the name of the cache as the single parameter. If the named cache does not exist, it is created. This method returns a Promise that resolves with the Cache object.

const cache = await caches.open('my-cache');
// do something with cache...

Adding to a cache #

There are three ways to add an item to a cache - add, addAll, and put. All three methods return a Promise.

`cache.add` #

First, there is cache.add(). It takes one parameter, either a Request or a URL (string). It makes a request to the network and stores the response in the cache. If the fetch fails, or if the status code of the response is not in the 200 range, then nothing is stored and the Promise rejects. Note that cross-origin requests not in CORS mode cannot be stored because they return a status of 0. Such requests can only be stored with put.

// Retreive data.json from the server and store the response.
cache.add(new Request('/data.json'));

// Retreive data.json from the server and store the response.
cache.add('/data.json');

`cache.addAll` #

Next, there is cache.addAll(). It works similarly to add(), but takes an array of Request objects or URLs (strings). This works similarly to calling cache.add for each individual request, except that the Promise rejects if any single request is not cached.

const urls = ['/weather/today.json', '/weather/tomorrow.json'];
cache.addAll(urls);

In each of these cases, a new entry overwrites any matching existing entry. This uses the same matching rules described in the section on retrieving.

`cache.put` #

Finally, there is cache.put(), which allows you to store either a response from the network, or create and store your own Response. It takes two parameters. The first can either be a Request object or a URL (string). The second must be a Response, either from the network, or generated by your code.

// Retrieve data.json from the server and store the response.
cache.put('/data.json');

// Create a new entry for test.json and store the newly created response.
cache.put('/test.json', new Response('{"foo": "bar"}'));

// Retrieve data.json from the 3rd party site and store the response.
cache.put('https://example.com/data.json');

The put() method is more permissive than either add() or addAll(), and will allow you to store non-CORS responses, or other responses where the status code of the response is not in the 200 range. It will overwrite any previous responses for the same request.

Creating Request objects #

Create the Request object using a URL for the thing being stored:

const request = new Request('/my-data-store/item-id');

Working with Response objects #

The Response object constructor accepts many types of data, including Blobs, ArrayBuffers, FormData objects, and strings.

const imageBlob = new Blob([data], {type: 'image/jpeg'});
const imageResponse = new Response(imageBlob);
const stringResponse = new Response('Hello world');

You can set the MIME type of a Response by setting the appropriate header.

  const options = {
    headers: {
      'Content-Type': 'application/json'
    }
  }
  const jsonResponse = new Response('{}', options);

If you have retrieved a Response and wish to access its body, there are several helper methods you can use. Each returns a Promise that resolves with a value of a different type.

Method	Description
`arrayBuffer`	Returns an `ArrayBuffer` containing the body, serialized to bytes.
`blob`	Returns a `Blob`. If the `Response` was created with a `Blob` then this new `Blob` has the same type. Otherwise, the `Content-Type` of the `Response` is used.
`text`	Interprets the bytes of the body as a UTF-8 encoded string.
`json`	Interprets the bytes of the body as a UTF-8 encoded string, then tries to parse it as JSON. Returns the resulting object, or throws a `TypeError` if the string cannot be parsed as JSON.
`formData`	Interprets the bytes of the body as an HTML form, encoded either as `multipart/form-data` or `application/x-www-form-urlencoded`. Returns a FormData object, or throws a `TypeError` if the data cannot be parsed.
`body`	Returns a ReadableStream for the body data.

For example

const response = new Response('Hello world');
const buffer = await response.arrayBuffer();
console.log(new Uint8Array(buffer));
// Uint8Array(11) [72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100]

Retrieving from a cache #

To find an item in a cache, you can use the match method.

const response = await cache.match(request);
console.log(request, response);

If request is a string the browser converts it to a Request by calling new Request(request). The function returns a Promise that resolves to a Response if a matching entry is found, or undefined otherwise.

To determine if two Requests match, the browser uses more than just the URL. Two requests are considered different if they have different query strings, Vary headers, or HTTP methods (GET, POST, PUT, etc.).

You can ignore some or all of these things by passing an options object as a second parameter.

const options = {
  ignoreSearch: true,
  ignoreMethod: true,
  ignoreVary: true
};

const response = await cache.match(request, options);
// do something with the response

If more than one cached request matches then the one that was created first is returned. If you want to retrieve all matching responses, you can use cache.matchAll().

const options = {
  ignoreSearch: true,
  ignoreMethod: true,
  ignoreVary: true
};

const responses = await cache.matchAll(request, options);
console.log(`There are ${responses.length} matching responses.`);

As a shortcut you can search over all caches at once by using caches.match() instead of calling cache.match() for each cache.

Searching #

The Cache API does not provide a way to search for requests or responses except for matching entries against a Response object. However, you can implement your own search using filtering or by creating an index.

Filtering #

One way to implement your own search is to iterate over all entries and filter down to the ones that you want. Let's say that you want to find all items that have URLs ending with .png.

async function findImages() {
  // Get a list of all of the caches for this origin
  const cacheNames = await caches.keys();
  const result = [];

  for (const name of cacheNames) {
    // Open the cache
    const cache = await caches.open(name);

    // Get a list of entries. Each item is a Request object
    for (const request of await cache.keys()) {
      // If the request URL matches, add the response to the result
      if (request.url.endsWith('.png')) {
        result.push(await cache.match(request));
      }
    }
  }

  return result;
}

This way you can use any property of the Request and Response objects to filter the entries. Note that this is slow if you search over large sets of data.

Creating an index #

The other way to implement your own search is to maintain a separate index of entries that can be searched and store the index in IndexedDB. Since this is the kind of operation that IndexedDB was designed for it has much better performance with large numbers of entries.

If you store the URL of the Request alongside the searchable properties then you can easily retrieve the correct cache entry after doing the search.

Deleting an item #

To delete an item from a cache:

cache.delete(request);

Where request can be a Request or a URL string. This method also takes the same options object as cache.match, which allows you to delete multiple Request/Response pairs for the same URL.

cache.delete('/example/file.txt', {ignoreVary: true, ignoreSearch: true});

Deleting a cache #

To delete a cache, call caches.delete(name). This function returns a Promise that resolves to true if the cache existed and was deleted, or false otherwise.

Thanks #

Thanks to Mat Scales who wrote the original version of this article, which first appeared on WebFundamentals.

WebAPKs on Android

2017-05-21T00:00:00Z

Installing a PWA on Android does more than just add the Progressive Web App to the user's Home Screen. Chrome automatically generates and installs a special APK of your app. We sometimes refer to this as a WebAPK. Being installed via an APK makes it possible for your app to show up in the app launcher, in Android's app settings and to register a set of intent filters.

To generate the WebAPK, Chrome looks at the web app manifest and other metadata. When an update to the manifest is detected, Chrome will need to generate a new APK.

Note: Since the WebAPK is regenerated each time an updated manifest is detected, we recommend changing it only when necessary. Don't use the manifest to store user specific identifiers, or other other data that might be customized. Frequently changing the manifest will increase the overall install time.

Android intent filters #

When a Progressive Web App is installed on Android, it will register a set of intent filters for all URLs within the scope of the app. When a user clicks on a link that is within the scope of the app, the app will be opened, rather than opening within a browser tab.

Consider the following partial manifest.json:

"start_url": "/",
"display": "standalone",

When a web app using it is launched from the app launcher, it would open https://example.com/ as a standalone app, without any browser chrome.

The WebAPK would include the following intent filters:

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data
    android:scheme="https"
    android:host="example.com"
    android:pathPrefix="/" />
</intent-filter>

If the user clicks on a link within an installed app to https://example.com/read, it would be caught by the intent and opened in the Progressive Web App.

Note: Navigating directly to https://example.com/app/ from the address bar in Chrome will work exactly the same as it does for native apps that have an intent filter. Chrome assumes the user intended to visit the site and will open this site.

Using `scope` to restrict intent filters #

If you don't want your Progressive Web App to handle all URLs within your site, you can add the scope property to your web app manifest. The scope property tells Android to only open your web app if the URL matches the origin + scope. It gives you control over which URLs will be handled by your app, and which should be opened in the browser. This is helpful when you have your app and other non-app content on the same domain.

Consider the following partial manifest.json:

"scope": "/app/",
"start_url": "/app/",
"display": "standalone",

When launched from the app launcher, it would open https://example.com/app/ as a standalone app, without any browser chrome.

Like before, the generated WebAPK would include an intent filter, but with a different android:pathPrefix attribute in the APK's AndroidManifest.xml:

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data
    android:scheme="https"
    android:host="example.com"
    android:pathPrefix="/app/" />
</intent-filter>

Let's take a look at a few examples:

https://example.com/app/ - within /app/

https://example.com/app/read/book - within /app/

Don't

https://example.com/help/ - not in /app/

Don't

https://example.com/about/ - not in /app/

See scope for more information about scope, what happens when you don't set it, and how you can use it to define the scope of your app.

Managing permissions #

Permissions work in the same way as other web apps and cannot be requested at install time. Instead, they must be requested at run time, ideally only when you really need them. For example, don't ask for camera permission on first load, but instead wait until the user attempts to take a picture.

Note: Android normally grants immediate permission to show notifications for installed apps, but apps installed via WebAPKs are not granted this at install time; you must request it at runtime within your app.

Managing storage and app state #

Even though the progressive web app is installed via an APK, Chrome uses the current profile to store any data, and it will not be segregated away. This allows a shared experience between the browser and the installed app. Cookies are shared and active, any client side storage is accessible and the service worker is installed and ready to go.

Note: Keep in mind that if the user clears their Chrome profile, or chooses to delete site data, that will apply to the WebAPK as well.

Updating the WebAPK #

Information on how a WebAPK is updated has moved to How Chrome handles updates to the web app manifest.

Frequently asked questions #

What icons are used to generate the splash screen? :: We recommend you provide at least two icons: 192px and 512px for the splash screen. We heard from you that icons on the splash screen were too small. WebAPKs generated in Chrome 71 or later will show a larger icon on the splash screen. No action is required, as long as the recommended icons are provided.
What happens if the user has already installed the native app for the site?: Like add to home screen today, users will be able to add a site independent of any native apps. If you expect users to potentially install both, we recommend differentiating the icon or name of your site from your native app.
Will my installed site's storage be cleared if the user clears Chrome's cache?: Yes.
Will my app be re-installed when I get a new device?: Not at this time, but we think it is an important area and we are investigating ways to make it work.
How are permissions handled? Will I see the Chrome prompt or Android's?: Permissions will still be managed through Chrome. Users will see the Chrome prompts to grant permissions and will be able to edit them in Chrome settings.
What versions of Android will this work on?: Progressive web apps can be installed on all versions of Android that run Chrome for Android, specifically Jelly Bean and above.
Does this use the WebView?: No, the site opens in the version of Chrome the user added the site from.
Can we upload the APKs that are created to the Play Store?: No. If you want to upload your own APK, check outTrusted Web Activities.
Are these listed in the Play Store?: No. If you want to upload your own APK for listing in the Play Store, check out Trusted Web Activities.
I am a developer of another browser on Android, can I have this seamless install process? :: We are working on it. We are committed to making this available to all browsers on Android and we will have more details soon.

Basics of UX

2016-06-30T00:00:00Z

Push notifications are an incredibly effective way to build deeper user engagement with your application, and are now available on the web. In this video, we'll take a look at how they work and deep-dive into how to implement push notifications in web applications, from beginning to end.

Click to Call

2014-06-17T00:00:00Z

On devices with phone capabilities, make it easy for users to directly connect with you by simply tapping a phone number, more commonly known as click to call.

Summary #

Wrap all phone numbers in hyperlinks with the tel: schema.
Always use the international dialing format.

Link telephone numbers for click to call #

While many modern mobile browsers automatically detect phone numbers and convert them to links, it’s a good idea to do this directly in your code. By manually tagging each phone number, you can ensure that phone numbers are always enabled for click to call and that they will be styled to match your site.

To mark a phone number as a link, use the tel: scheme. The syntax is simple:

NIST Telephone Time-of-Day Service
<a href="tel:+1-303-499-7111">+1 (303) 499-7111</a>

Your browser displays this syntax as follows:

NIST Telephone Time-of-Day Service +1 (303) 499-7111

Click to call example

On most devices with telephone capabilities, the user receives a confirmation before the number is dialed, to ensure that the user isn't being tricked into calling an expensive long distance or premium phone number. When the device doesn’t support phone calls, users may be presented with a menu allowing them to choose how the browser should handle the number.

Desktop browsers that don’t support voice calls open the default telephony app on the computer; for example Google Voice or Microsoft Communicator.

Use the international dialing format #

Always supply the phone number using the international dialing format: the plus sign (+), country code, area code, and number. While not absolutely necessary, it’s a good idea to separate each segment of the number with a hyphen (-) for easier reading and better auto-detection.

Using a hyphenated international dialing format ensures that no matter where the user is calling from, whether a few hundred meters away or thousands of kilometers, their call will be connected.

Disable auto-detection when necessary #

Modern mobile browsers automatically detect phone numbers and enable click to call. Mobile Safari automatically converts phone numbers to links with the associated hyperlink styles. Chrome for Android automatically detects phone numbers and allows users to click to call, but does not wrap the phone numbers in hyperlinks or apply any special styles.

To prevent Mobile Safari from automatically detecting phone numbers, add the following meta tag to your page:

<meta name="format-detection" content="telephone=no" />

Other click to call features #

In addition to the tel: schema, some modern browsers also support the sms: and mms: schemas, though support is not as consistent, and some features like setting the message body don't always work.

Feedback #

Device Orientation & Motion

2014-06-17T00:00:00Z

Device motion and orientation events provide access to the built-in accelerometer, gyroscope, and compass in mobile devices.

These events can be used for many purposes; in gaming, for example, to control the direction or action of a character. When used with geolocation, they can help create more accurate turn-by-turn navigation or provide information about a specific location.

Summary #

Detect which side of the device is up and how the device is rotating.
Learn when and how to respond to motion and orientation events.

Which end is up? #

To use the data that the device orientation and motion events return, it is important to understand the values provided.

Earth coordinate frame #

The Earth coordinate frame, described by the values X, Y, and Z, is aligned based on gravity and standard magnetic orientation.

Coordinate system
`X`	Represents the east-west direction (where east is positive).
`Y`	Represents the north-south direction (where north is positive).
`Z`	Represents the up-down direction, perpendicular to the ground (where up is positive).

Device coordinate frame #

Illustration of device coordinate frame

The device coordinate frame, described by the values x, y, and z, is aligned based on the center of the device.

Coordinate system
`X`	In the plane of the screen, positive to the right.
`Y`	In the plane of the screen, positive towards the top.
`Z`	Perpendicular to the screen or keyboard, positive extending away.

On a phone or tablet, the orientation of the device is based on the typical orientation of the screen. For phones and tablets, it is based on the device being in portrait mode. For desktop or laptop computers, the orientation is considered in relation to the keyboard.

Rotation data #

Rotation data is returned as a Euler angle, representing the number of degrees of difference between the device coordinate frame and the Earth coordinate frame.

Alpha #

Illustration of alpha in the device coordinate frame

The rotation around the z axis. The alpha value is 0° when the top of the device is pointed directly north. As the device is rotated counter-clockwise, the alpha value increases.

Beta #

Illustration of beta in the device coordinate frame

The rotation around the x axis. The beta value is 0° when the top and bottom of the device are equidistant from the surface of the earth. The value increases as the top of the device is tipped toward the surface of the earth.

Gamma #

Illustration of gamma in the device coordinate frame

The rotation around the y axis. The gamma value is 0° when the left and right edges of the device are equidistant from the surface of the earth. The value increases as the right side is tipped towards the surface of the earth.

Device orientation #

The device orientation event returns rotation data, which includes how much the device is leaning front-to-back, side-to-side, and, if the phone or laptop has a compass, the direction the device is facing.

Use sparingly. Test for support. Don't update the UI on every orientation event; instead, sync to requestAnimationFrame.

When to use device orientation events #

There are several uses for device orientation events. Examples include the following:

Update a map as the user moves.
Subtle UI tweaks, for example, adding parallax effects.
Combined with geolocation, can be used for turn-by-turn navigation.

Check for support and listen for events #

To listen for DeviceOrientationEvent, first check to see if the browser supports the events. Then, attach an event listener to the window object listening for deviceorientation events.

if (window.DeviceOrientationEvent) {
  window.addEventListener('deviceorientation', deviceOrientationHandler, false);
  document.getElementById('doeSupported').innerText = 'Supported!';
}

Handle the device orientation events #

The device orientation event fires when the device moves or changes orientation. It returns data about the difference between the device in its current position in relation to the Earth coordinate frame.

The event typically returns three properties: alpha, beta, and gamma. On Mobile Safari, an additional parameter webkitCompassHeading is returned with the compass heading.

Device motion #

Use device motion for when the current motion of the device is needed. rotationRate is provided in °/sec. acceleration and accelerationWithGravity are provided in m/sec². Be aware of differences between browser implementations.

When to use device motion events #

There are several uses for device motion events. Examples include the following:

Shake gesture to refresh data.
In games, to cause characters to jump or move.
For health and fitness apps.

Check for support and listen for events #

To listen for DeviceMotionEvent, first check to see if the events are supported in the browser. Then attach an event listener to the window object listening for devicemotion events.

if (window.DeviceMotionEvent) {
  window.addEventListener('devicemotion', deviceMotionHandler);
  setTimeout(stopJump, 3 * 1000);
}

Handle the device motion events #

The device motion event fires on a regular interval and returns data about the rotation (in °/second) and acceleration (in m/second²) of the device, at that moment in time. Some devices do not have the hardware to exclude the effect of gravity.

The event returns four properties, accelerationIncludingGravity, acceleration, which excludes the effects of gravity, rotationRate, and interval.

For example, let's take a look at a phone, lying on a flat table, with its screen facing up.

State	Rotation	Acceleration (m/s²)	Acceleration with gravity (m/s²)
Not moving	[0, 0, 0]	[0, 0, 0]	[0, 0, 9.8]
Moving up towards the sky	[0, 0, 0]	[0, 0, 5]	[0, 0, 14.81]
Moving only to the right	[0, 0, 0]	[3, 0, 0]	[3, 0, 9.81]
Moving up and to the right	[0, 0, 0]	[5, 0, 5]	[5, 0, 14.81]

Conversely, if the phone were held so the screen was perpendicular to the ground, and was directly visible to the viewer:

State	Rotation	Acceleration (m/s²)	Acceleration with gravity (m/s²)
Not moving	[0, 0, 0]	[0, 0, 0]	[0, 9.81, 0]
Moving up towards the sky	[0, 0, 0]	[0, 5, 0]	[0, 14.81, 0]
Moving only to the right	[0, 0, 0]	[3, 0, 0]	[3, 9.81, 0]
Moving up and to the right	[0, 0, 0]	[5, 5, 0]	[5, 14.81, 0]

Sample: Calculating the maximum acceleration of an object #

One way to use device motion events is to calculate the maximum acceleration of an object. For example, what's the maximum acceleration of a person jumping?

if (evt.acceleration.x > jumpMax.x) {
  jumpMax.x = evt.acceleration.x;
}
if (evt.acceleration.y > jumpMax.y) {
  jumpMax.y = evt.acceleration.y;
}
if (evt.acceleration.z > jumpMax.z) {
  jumpMax.z = evt.acceleration.z;
}

After tapping the Go! button, the user is told to jump. During that time, the page stores the maximum (and minimum) acceleration values, and after the jump, tells the user their maximum acceleration.

Feedback #

Responsive images

2014-04-29T00:00:00Z

Responsive web design means that not only can our layouts change based on device characteristics, but content can change as well. For example, on high resolution (2x) displays, high resolution graphics ensure sharpness. An image that is 50% width may work just fine when the browser is 800px wide, but uses too much real estate on a narrow phone, and requires the same bandwidth overhead when scaled down to fit a smaller screen.

Art direction #

Other times the image may need to be changed more drastically: changing the proportions, cropping, and even replacing the entire image. In this case, changing the image is usually referred to as art direction. See responsiveimages.org/demos/ for more examples.

Responsive Images #

Did you know that images account for more than 60% of the bytes on average needed to load a web page?

In this course you will learn how to work with images on the modern web, so that your images look great and load quickly on any device.

Along the way, you will pick up a range of skills and techniques to smoothly integrate responsive images into your development workflow. By the end of the course, you will be developing with images that adapt and respond to different viewport sizes and usage scenarios.

This is a free course offered through Udacity

Take Course

Images in markup #

The img element is powerful—it downloads, decodes, and renders content—and modern browsers support a range of image formats. Including images that work across devices is no different than for desktop, and only requires a few minor tweaks to create a good experience.

Summary #

Use relative sizes for images to prevent them from accidentally overflowing the container.
Use the picture element when you want to specify different images depending on device characteristics (a.k.a. art direction).
Use srcset and the x descriptor in the img element to give hints to the browser about the best image to use when choosing from different densities.
If your page only has one or two images and these are not used elsewhere on your site, consider using inline images to reduce file requests.

Use relative sizes for images #

Remember to use relative units when specifying widths for images to prevent them from accidentally overflowing the viewport. For example, width: 50%; causes the image width to be 50% of the containing element (not 50% of the viewport or 50% of actual pixel size).

Because CSS allows content to overflow its container, you may need to use max- width: 100% to prevent images and other content from overflowing. For example:

img, embed, object, video {
    max-width: 100%;
}

Be sure to provide meaningful descriptions via the alt attribute on img elements; these help make your site more accessible by giving context to screen readers and other assistive technologies.

Enhance `img`s with `srcset` for high DPI devices #

The srcset attribute enhances the behavior of the img element, making it easy to provide multiple image files for different device characteristics. Similar to the image-set CSS function native to CSS, srcset allows the browser to choose the best image depending on the characteristics of the device, for example using a 2x image on a 2x display, and potentially in the future, a 1x image on a 2x device when on a limited bandwidth network.

<img src="photo.png" srcset="photo@2x.png 2x" ...>

On browsers that don't support srcset, the browser simply uses the default image file specified by the src attribute. This is why it is important to always include a 1x image that can be displayed on any device, regardless of capabilities. When srcset is supported, the comma-separated list of image/conditions is parsed prior to making any requests, and only the most appropriate image is downloaded and displayed.

While the conditions can include everything from pixel density to width and height, only pixel density is well-supported today. To balance current behavior with future features, stick with simply providing the 2x image in the attribute.

Art direction in responsive images with `picture` #

To change images based on device characteristics, also known as art direction, use the picture element. The picture element defines a declarative solution for providing multiple versions of an image based on different characteristics, like device size, device resolution, orientation, and more.

Use the picture element when an image source exists in multiple densities, or when a responsive design dictates a somewhat different image on some types of screens. Similar to the video element, multiple source elements can be included, making it possible to specify different image files depending on media queries or image format.

<picture>
  <source media="(min-width: 800px)" srcset="head.jpg, head-2x.jpg 2x">
  <source media="(min-width: 450px)" srcset="head-small.jpg, head-small-2x.jpg 2x">
  <img src="head-fb.jpg" srcset="head-fb-2x.jpg 2x" alt="a head carved out of wood">
</picture>

Try it

In the above example, if the browser width is at least 800px then either head.jpg or head-2x.jpg is used, depending on the device resolution. If the browser is between 450px and 800px, then either head-small.jpg or head-small- 2x.jpg is used, again, depending on the device resolution. For screen widths less than 450px and backward compatibility where the picture element isn’t supported, the browser renders the img element instead, and should always be included.

Relative sized images #

When the final size of the image isn’t known, it can be difficult to specify a density descriptor for the image sources. This is especially true for images that span a proportional width of the browser and are fluid, depending on the size of the browser.

Instead of supplying fixed image sizes and densities, you can specify the size of each supplied image by adding a width descriptor along with the size of the image element, allowing the browser to automatically calculate the effective pixel density and choose the best image to download.

<img src="lighthouse-200.jpg" sizes="50vw"
     srcset="lighthouse-100.jpg 100w, lighthouse-200.jpg 200w,
             lighthouse-400.jpg 400w, lighthouse-800.jpg 800w,
             lighthouse-1000.jpg 1000w, lighthouse-1400.jpg 1400w,
             lighthouse-1800.jpg 1800w" alt="a lighthouse">

Try it

The above example renders an image that is half the viewport width (sizes="50vw"), and depending on the width of the browser and its device pixel ratio, allows the browser to choose the correct image regardless of how large the browser window is. For example, the table below shows which image the browser would choose:

Browser width	Device pixel ratio	Image used	Effective resolution
400px	1	`200.jpg`	1x
400px	2	`400.jpg`	2x
320px	2	`400.jpg`	2.5x
600px	2	`800.jpg`	2.67x
640px	3	`1000.jpg`	3.125x
1100px	1	`800.png`	1.45x

Account for breakpoints in responsive images #

In many cases, the image size may change depending on the site’s layout breakpoints. For example, on a small screen, you might want the image to span the full width of the viewport, while on larger screens, it should only take a small proportion.

<img src="400.png"
     sizes="(min-width: 600px) 25vw, (min-width: 500px) 50vw, 100vw"
     srcset="100.png 100w, 200.png 200w, 400.png 400w,
             800.png 800w, 1600.png 1600w, 2000.png 2000w" alt="an example image">

Try it

The sizes attribute, in the above example, uses several media queries to specify the size of the image. When the browser width is greater than 600px, the image is 25% of the viewport width; when it is between 500px and 600px, the image is 50% of the viewport width; and below 500px, it is full width.

Make product images expandable #

J. Crew's website with expandable product image.

Customers want to see what they're buying. On retail sites, users expect to be able to view high resolution closeups of products to get a better look at details, and study participants got frustrated if they weren't able to.

A good example of tappable, expandable images is provided by the J. Crew site. A disappearing overlay indicates that an image is tappable, providing a zoomed in image with fine detail visible.

Other image techniques #

Compressive images #

The compressive image technique serves a highly compressed 2x image to all devices, no matter the actual capabilities of the device. Depending on the type of image and level of compression, image quality may not appear to change, but the file size drops significantly.

Try it

JavaScript image replacement #

JavaScript image replacement checks the capabilities of the device and "does the right thing." You can determine device pixel ratio via window.devicePixelRatio, get screen width and height, and even potentially do some network connection sniffing via navigator.connection or issuing a fake request. When you've collected all of this information, you can decide which image to load.

One big drawback to this approach is that using JavaScript means that you will delay image loading until at least the look-ahead parser has finished. This means that images won't even start downloading until after the pageload event fires. In addition, the browser will most likely download both the 1x and 2x images, resulting in increased page weight.

Inlining images: raster and vector #

There are two fundamentally different ways to create and store images—and this affects how you deploy images responsively.

Raster images — such as photographs and other images, are represented as a grid of individual dots of color. Raster images might come from a camera or scanner, or be created with the HTML canvas element. Formats like PNG, JPEG, and WebP are used to store raster images.

Vector images such as logos and line art are defined as a set of curves, lines, shapes, fill colors and gradients. Vector images can be created with programs like Adobe Illustrator or Inkscape, or handwritten in code using a vector format such as SVG.

SVG #

SVG makes it possible to include responsive vector graphics in a web page. The advantage of vector file formats over raster file formats is that the browser can render a vector image at any size. Vector formats describe the geometry of the image—how it's constructed from lines, curves, and colors and so on. Raster formats, on the other hand, only have information about individual dots of color, so the browser has to guess how to fill in the blanks when scaling.

Below are two versions of the same image: a PNG image on the left and an SVG on the right. The SVG looks great at any size, whereas the PNG next to it starts to look blurry at larger display sizes.

If you want to reduce the number of file requests your page makes, you can code images inline using SVG or Data URI format. If you view the source of this page, you'll see that both logos below are declared inline: a Data URI and an SVG.

SVG has great support on mobile and desktop, and optimization tools can significantly reduce SVG size. The following two inline SVG logos look identical, but one is around 3KB and the other only 2KB:

Data URI #

Data URIs provide a way to include a file, such as an image, inline by setting the src of an img element as a Base64 encoded string using the following format:

<img src="data:image/svg+xml;base64,[data]">

The start of the code for the HTML5 logo above looks like this:

<img src="data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjwhLS0gR2VuZXJhdG9yOiB
BZG9iZSBJbGx1c3RyYXRvciAxNi4wLjAsIFNWRyBFeHBvcnQgUGx1Zy1JbiAuIFNWRyBWZXJzaW ...">

(The full version is over 5000 characters in length!)

Drag 'n' drop tool such as jpillora.com/base64-encoder are available to convert binary files such as images to Data URIs. Just like SVGs, Data URIs are well supported on mobile and desktop browsers.

Inlining in CSS #

Data URIs and SVGs can also be inlined in CSS—and this is supported on both mobile and desktop. Here are two identical-looking images implemented as background images in CSS; one Data URI, one SVG:

Inlining pros & cons #

Inline code for images can be verbose—especially Data URIs—so why would you want to use it? To reduce HTTP requests! SVGs and Data URIs can enable an entire web page, including images, CSS and JavaScript, to be retrieved with one single request.

On the downside:

On mobile, Data URIs can be significantly slower to display on mobile than images from an external src.
Data URIs can considerably increase the size of an HTML request.
They add complexity to your markup and your workflow.
The Data URI format is considerably bigger than binary (up to 30%) and therefore doesn't reduce total download size.
Data URIs cannot be cached, so must be downloaded for every page they're used on.
They're not supported in IE 6 and 7, incomplete support in IE8.
With HTTP/2, reducing the number of asset requests will become less of a priority.

As with all things responsive, you need to test what works best. Use developer tools to measure download file size, the number of requests, and the total latency. Data URIs can sometimes be useful for raster images—for example, on a homepage that only has one or two photos that aren't used elsewhere. If you need to inline vector images, SVG is a much better option.

Images in CSS #

The CSS background property is a powerful tool for adding complex images to elements, making it easy to add multiple images, and causing them to repeat, and more. When combined with media queries, the background property becomes even more powerful, enabling conditional image loading based on screen resolution, viewport size, and more.

Summary #

Use the best image for the characteristics of the display, consider screen size, device resolution, and page layout.
Change the background-image property in CSS for high DPI displays using media queries with min-resolution and -webkit-min-device-pixel-ratio.
Use srcset to provide high resolution images in addition to the 1x image in markup.
Consider the performance costs when using JavaScript image replacement techniques or when serving highly compressed high resolution images to lower resolution devices.

Use media queries for conditional image loading or art direction #

Media queries not only affect the page layout; you can also use them to conditionally load images or to provide art direction depending on the viewport width.

For example, in the sample below, on smaller screens only small.png is downloaded and applied to the content div, while on larger screens background-image: url(body.png) is applied to the body and background-image: url(large.png) is applied to the content div.

.example {
  height: 400px;
  background-image: url(small.png);
  background-repeat: no-repeat;
  background-size: contain;
  background-position-x: center;
}

@media (min-width: 500px) {
  body {
    background-image: url(body.png);
  }
  .example {
    background-image: url(large.png);
  }
}

Try it

Use image-set to provide high res images #

The image-set() function in CSS enhances the behavior background property, making it easy to provide multiple image files for different device characteristics. This allows the browser to choose the best image depending on the characteristics of the device, for example using a 2x image on a 2x display, or a 1x image on a 2x device when on a limited bandwidth network.

background-image: image-set(
    url(icon1x.jpg) 1x,
    url(icon2x.jpg) 2x
);

In addition to loading the correct image, the browser also scales it accordingly. In other words, the browser assumes that 2x images are twice as large as 1x images, and so scales the 2x image down by a factor of 2, so that the image appears to be the same size on the page.

Support for image-set() is still new and is only supported in Chrome and Safari with the -webkit vendor prefix. Take care to include a fallback image for when image-set() is not supported; for example:

.sample {
  width: 128px;
  height: 128px;
  background-image: url(icon1x.png);
  background-image: -webkit-image-set(
    url(icon1x.png) 1x,
    url(icon2x.png) 2x
  );
  background-image: image-set(
    url(icon1x.png) 1x,
    url(icon2x.png) 2x
  );
}

Try it

The above loads the appropriate asset in browsers that support image-set; otherwise it falls back to the 1x asset. The obvious caveat is that while image-set() browser support is low, most browsers get the 1x asset.

Use media queries to provide high res images or art direction #

Media queries can create rules based on the device pixel ratio, making it possible to specify different images for 2x versus 1x displays.

@media (min-resolution: 2dppx),
(-webkit-min-device-pixel-ratio: 2)
{
    /* High dpi styles & resources here */
}

Chrome, Firefox, and Opera all support the standard (min-resolution: 2dppx), while the Safari and Android browsers both require the older vendor prefixed syntax without the dppx unit. Remember, these styles are only loaded if the device matches the media query, and you must specify styles for the base case. This also provides the benefit of ensuring something is rendered if the browser doesn't support resolution-specific media queries.

.sample {
  width: 128px;
  height: 128px;
  background-image: url(icon1x.png);
}

@media (min-resolution: 2dppx), /* Standard syntax */
(-webkit-min-device-pixel-ratio: 2)  /* Safari & Android Browser */
{
  .sample {
    background-size: contain;
    background-image: url(icon2x.png);
  }
}

Try it

You can also use the min-width syntax to display alternative images depending on the viewport size. This technique has the advantage that the image is not downloaded if the media query doesn't match. For example, bg.png is only downloaded and applied to the body if the browser width is 500px or greater:

@media (min-width: 500px) {
    body {
    background-image: url(bg.png);
    }
}

Use SVG for icons #

When adding icons to your page, use SVG icons where possible or in some cases, unicode characters.

Summary #

Use SVG or unicode for icons instead of raster images.

Replace simple icons with unicode #

Many fonts include support for the myriad of unicode glyphs, which can be used instead of images. Unlike images, unicode fonts scale well and look good no matter how small or large they appear on screen.

Beyond the normal character set, unicode may include symbols for arrows (←), math operators (√), geometric shapes (★), control pictures (▶), music notation (♬), Greek letters (Ω), even chess pieces (♞).

Including a unicode character is done in the same way named entities are: &#XXXX, where XXXX represents the unicode character number. For example:

You're a super &#9733;

You're a super ★

Replace complex icons with SVG #

For more complex icon requirements, SVG icons are generally lightweight, easy to use, and can be styled with CSS. SVG have a number of advantages over raster images:

They're vector graphics that can be infinitely scaled.
CSS effects such as color, shadowing, transparency, and animations are straightforward.
SVG images can be inlined right in the document.
They are semantic.
They provide better accessibility with the appropriate attributes.

With SVG icons, you can either add icons using inline SVG, like
this checkmark:
  <svg version="1.1" xmlns="http://www.w3.org/2000/svg"
       xmlns:xlink="http://www.w3.org/1999/xlink"
       width="32" height="32" viewBox="0 0 32 32">
    <path d="M27 4l-15 15-7-7-5 5 12 12 20-20z" fill="#000000"></path>
  </svg>
or by using an image tag, like this credit card icon:
<img src="credit.svg">.

Try it

Use icon fonts with caution #

Example of a page that uses FontAwesome for its font icons.

Icon fonts are popular, and can be easy to use, but have some drawbacks compared to SVG icons:

They're vector graphics that can be infinitely scaled, but may be anti-aliased resulting in icons that aren’t as sharp as expected.
Limited styling with CSS.
Pixel perfect positioning can be difficult, depending on line-height, letter spacing, etc.
They aren't semantic, and can be difficult to use with screen readers or other assistive technology.
Unless properly scoped, they can result in a large file size for only using a small subset of the icons available.

With Font Awesome, you can either add icons by using a unicode
entity, like this HTML5 logo (<span class="awesome">&#xf13b;</span>)
or by adding special classes to an &lt;i&gt; element like the CSS3
logo (<i class="fa fa-css3"></i>).

Try it

There are hundreds of free and paid icon fonts available including Font Awesome, Pictos, and Glyphicons.

Be sure to balance the weight of the additional HTTP request and file size with the need for the icons. For example, if you only need a handful of icons, it may be better to use an image or an image sprite.

Optimize images for performance #

Images often account for most of the downloaded bytes and also often occupy a significant amount of the visual space on the page. As a result, optimizing images can often yield some of the largest byte savings and performance improvements for your website: the fewer bytes the browser has to download, the less competition there is for client's bandwidth and the faster the browser can download and display all the assets.

Summary #

Don't just randomly choose an image format—understand the different formats available and use the format best suited.
Include image optimization and compression tools into your workflow to reduce file sizes.
Reduce the number of http requests by placing frequently used images into image sprites.
To improve the initial page load time and reduce the initial page weight, consider loading images only after they’ve scrolled into view.

Choose the right format #

There are two types of images to consider: vector images and raster images. For raster images, you also need to choose the right compression format, for example: GIF, PNG, JPG.

Raster images, like photographs and other images, are represented as a grid of individual dots or pixels. Raster images typically come from a camera or scanner, or can be created in the browser with the canvas element. As the image size gets larger, so does the file size. When scaled larger than their original size, raster images become blurry because the browser needs to guess how to fill in the missing pixels.

Vector images, such as logos and line art, are defined by a set of curves, lines, shapes, and fill colors. Vector images are created with programs like Adobe Illustrator or Inkscape and saved to a vector format like SVG. Because vector images are built on simple primitives, they can be scaled without any loss in quality or change in file size.

When choosing the appropriate format, it is important to consider both the origin of the image (raster or vector), and the content (colors, animation, text, etc). No one format fits all image types, and each has its own strengths and weaknesses.

Start with these guidelines when choosing the appropriate format:

Use JPG for photographic images.
Use SVG for vector art and solid color graphics such as logos and line art. If vector art is unavailable, try WebP or PNG.
Use PNG rather than GIF as it allows for more colors and offers better compression ratios.
For longer animations consider using <video>, which provides better image quality and gives the user control over playback.

Reduce the file size #

You can reduce image file size considerably by "post-processing" the images after saving. There are a number of tools for image compression—lossy and lossless, online, GUI, command line. Where possible, it's best to try automating image optimization so that it's a built-in to your workflow.

Several tools are available that perform further, lossless compression on JPG and PNG files with no effect on image quality. For JPG, try jpegtran or jpegoptim (available on Linux only; run with the --strip-all option). For PNG, try OptiPNG or PNGOUT.

Use image sprites #

CSS spriting is a technique whereby a number of images are combined into a single "sprite sheet" image. You can then use individual images by specifying the background image for an element (the sprite sheet) plus an offset to display the correct part.

.sprite-sheet {
  background-image: url(sprite-sheet.png);
  width: 40px;
  height: 25px;
}

.google-logo {
  width: 125px;
  height: 45px;
  background-position: -190px -170px;
}

.gmail {
  background-position: -150px -210px;
}

.maps {
  height: 40px;
  background-position: -120px -165px;
}

Try it

Spriting has the advantage of reducing the number of downloads required to get multiple images, while still enabling caching.

Consider lazy loading #

Lazy loading can significantly speed up loading on long pages that include many images below the fold by loading them either as needed or when the primary content has finished loading and rendering. In addition to performance improvements, using lazy loading can create infinite scrolling experiences.

Be careful when creating infinite scrolling pages—because content is loaded as it becomes visible, search engines may never see that content. In addition, users who are looking for information they expect to see in the footer, never see the footer because new content is always loaded.

Avoid images completely #

Sometimes the best image isn't actually an image at all. Whenever possible, use the native capabilities of the browser to provide the same or similar functionality. Browsers generate visuals that would have previously required images. This means that browsers no longer need to download separate image files thus preventing awkwardly scaled images. You can use unicode or special icon fonts to render icons.

Place text in markup instead of embedded in images #

Wherever possible, text should be text and not embedded into images. For example, using images for headlines or placing contact information—like phone numbers or addresses—directly into images prevents users from copying and pasting the information; it makes the information inaccessible for screen readers, and it isn't responsive. Instead, place the text in your markup and if necessary use webfonts to achieve the style you need.

Use CSS to replace images #

Modern browsers can use CSS features to create styles that would previously have required images. For example: complex gradients can be created using the background property, shadows can be created using box-shadow, and rounded corners can be added with the border-radius property.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque sit amet augue eu magna scelerisque porta ut ut dolor. Nullam placerat egestas nisl sed sollicitudin. Fusce placerat, ipsum ac vestibulum porta, purus dolor mollis nunc, pharetra vehicula nulla nunc quis elit. Duis ornare fringilla dui non vehicula. In hac habitasse platea dictumst. Donec ipsum lectus, hendrerit malesuada sapien eget, venenatis tempus purus.

<style>
    div#noImage {
    color: white;
    border-radius: 5px;
    box-shadow: 5px 5px 4px 0 rgba(9,130,154,0.2);
    background: linear-gradient(rgba(9, 130, 154, 1), rgba(9, 130, 154, 0.5));
    }
</style>

Keep in mind that using these techniques does require rendering cycles, which can be significant on mobile. If over-used, you'll lose any benefit you may have gained and it may hinder performance.

Movi Kanti Revo - Part 1 - Building the 3D World

2012-09-19T00:00:00Z

Movi.Kanti.Revo is a new sensory Chrome experiment crafted by Cirque du Soleil and developed by Subatomic Systems that brings the wonder of Cirque du Soleil to the web through modern web technologies.

Building the 3D World #

The experiment was created using just HTML5, and the environment is built entirely with markup and CSS. Like set pieces on stage, divs, imgs, small videos and other elements are positioned in a 3D space using CSS. Using the new getUserMedia API enabled a whole new way of interacting with the experiment, instead of using the keyboard or mouse, a JavaScript facial detection library tracks your head and moves the environment along with you.

All the Web's a Stage #

To build this experiment, it’s best to imagine the browser as a stage, and the elements like <div>s, images, videos and other elements as set pieces positioned in 3D space using CSS. Each element, or set piece is positioned on the stage by applying a 3D transform. If you’re unfamiliar with the translate3d transform, it takes 3 parameters, X, Y and Z. X moves the element along a horizontal line, Y moves the element up and down, and Z moves the element closer or further away. For example, applying a transform: translate3d(100px, -200px, 300px) will move the element 100 pixels to the right, 200 pixels down and 300 pixels closer towards the viewer.

Building the Auditorium #

Let’s take a look at the last scene and to see how it’s put together. All scenes are broken down into three primary containers, the world container, a perspective container and the stage. The world container effectively setups up the viewers camera, and uses the CSS perspective property to tell the browser where the viewer will be looking at the element from. The #perspective-container is used to change our perspective by applying 3D transforms to it. Finally, the stage contains the actual set pieces that will be visible on screen.

<div id="world-container">
  <div id="perspective-container">
    <div id="stage">
    </div>
  </div>
</div>

#world-container {
perspective: 700px;
overflow: hidden;
}

#perspective-container {
{ % mixin transform-style: preserve-3d; % }
{ % mixin transform-origin: center center; % }
{ % mixin perspective-origin: center center; % }
{ % mixin transform: translate3d(0, 0, 0) rotateX(0deg) rotateY(0deg) rotateZ(0deg); % }
}

Visualizing the Stage #

Within the stage, there are seven elements in the final scene. Moving from back to front, they include the sky background, a fog layer, the doors, the water, reflections, an additional fog layer, and finally the cliffs in front. Each item is placed on stage with a transform: translate3d(x, y, z) CSS property that indicates where it fits in 3D space. We used the z value in a similar way that we’d use z-index, but with the translate3d property, we can also provide a unit with the value.

Figure 1: The stage from the side.

Figure 1 shows the scene zoomed out and rotated almost 90 degrees so that you can visualize the way each of the different set pieces are placed within the stage. At the back (furthest to the left), you can see the background, fog, doors, water and finally the cliffs.

Placing the Background on Stage #

Let’s start with the background image. Since it’s the furthest back, we applied a -990px transform on the Z-axis to push it back in our perspective (see Figure 2).

Figure 2: The stage, with only the background placed at -990px

As it moves back in space, physics demands that it gets smaller, so it needs to be resized via a scale(3.3) property to fit the viewport and aligned the top edge with the top of the viewport with a translate3d on the y-axis (see Figure 3).

.background {
width: 1280px;
height: 800px;
top: 0px;
background-image: url(stars.png);
{ % mixin transform: translate3d(0, 786px, <b>-990px</b>) <b>scale(3.3)</b>; % }
}

Figure 3: The stage, with only the background positioned and scaled.

The fog, doors, and the cliffs in the same way, each by applying a translate3d with an appropriate z position and scale factor (see Figure 4). Notice how the fog is stacked behind the doors, and behind the cliffs.

Figure 4: The stage, with fog, doors and cliff positioned and scaled.

Adding the Sea #

To create as realistic an environment as possible, we knew we couldn’t simply put the water on a vertical plane, it’s typically doesn’t exist that way in the real world. In addition to applying the translate3d to position the water on stage, we also apply an x-axis (horizontal) rotation of 60 degrees (rotateX(60deg)) to make it appear flat and textured. A similar rotation was added to the door reflection and secondary fog to make it appear in the correct plane (see Figure 5).

.sea {
bottom: 120px;
background-image: url(sea2.png);
width: 1280px;
height: 283px;
{ % mixin transform: translate3d(-100px, 225px, -30px) scale(2.3) <b>rotateX(60deg)</b>; % }
}

Figure 5: The stage, with everything positioned and scaled.

Each scene was built in a similar fashion, elements were visualized within the 3D space of a stage, and an appropriate transform was applied to each.

Read files in JavaScript

2010-06-18T00:00:00Z

Selecting and interacting with files on the user's local device is one of the most commonly used features of the web. It allows users to select files and upload them to a server, for example, uploading photos, or submitting tax documents, etc. But, it also allows sites to read and manipulate them without ever having to transfer the data across the network.

The modern File System Access API #

The File System Access API provides an easy way to both read from and write to files and directories on the user's local system. It's currently available in most Chromium-based browsers such as Chrome or Edge. To learn more about it, see the File System Access API article.

Since the File System Access API is not compatible with all browsers yet, check out browser-fs-access, a helper library that uses the new API wherever it is available, but falls back to legacy approaches when it is not.

Working with files, the classic way #

This guide shows you how to:

Select files
- Using the HTML input element
- Using a drag-and-drop zone
Read file metadata
Read a file's content

Select files #

HTML input element #

The easiest way for users to select files is using the <input type="file"> element, which is supported in every major browser. When clicked, it lets a user select a file, or multiple files if the multiple attribute is included, using their operating system's built-in file selection UI. When the user finishes selecting a file or files, the element's change event fires. You can access the list of files from event.target.files, which is a FileList object. Each item in the FileList is a File object.

<!-- The `multiple` attribute lets users select multiple files. -->
<input type="file" id="file-selector" multiple>
<script>
  const fileSelector = document.getElementById('file-selector');
  fileSelector.addEventListener('change', (event) => {
    const fileList = event.target.files;
    console.log(fileList);
  });
</script>

This example lets a user select multiple files using their operating system's built-in file selection UI and then logs each selected file to the console.

Limit the types of files users can select #

In some cases, you may want to limit the types of files users can select. For example, an image editing app should only accept images, not text files. To do that, add an accept attribute to the input element to specify which file types are accepted.

<input type="file" id="file-selector" accept=".jpg, .jpeg, .png">

Custom drag-and-drop #

In some browsers, the <input type="file"> element is also a drop target, allowing users to drag-and-drop files into your app. But, the drop target is small, and can be hard to use. Instead, once you've provided the core functionality using an <input type="file"> element, you can provide a large, custom drag-and-drop surface.

Choose your drop zone #

Your drop surface depends on the design of your application. You may only want part of the window to be a drop surface, or potentially the entire window.

Squoosh makes the entire window a drop zone.

Squoosh allows the user to drag and drop an image anywhere into the window, and clicking select an image invokes the <input type="file"> element. Whatever you choose as your drop zone, make sure it's clear to the user that they can drag and drop files onto that surface.

Define the drop zone #

To enable an element to be a drag-and-drop zone, you'll need to listen for two events, dragover and drop. The dragover event updates the browser UI to visually indicate that the drag-and-drop action is creating a copy of the file. The drop event is fired after the user drops the files onto the surface. Similar to the input element, you can access the list of files from event.dataTransfer.files, which is a FileList object. Each item in the FileList is a File object.

const dropArea = document.getElementById('drop-area');

dropArea.addEventListener('dragover', (event) => {
  event.stopPropagation();
  event.preventDefault();
  // Style the drag-and-drop as a "copy file" operation.
  event.dataTransfer.dropEffect = 'copy';
});

dropArea.addEventListener('drop', (event) => {
  event.stopPropagation();
  event.preventDefault();
  const fileList = event.dataTransfer.files;
  console.log(fileList);
});

event.stopPropagation() and event.preventDefault() stop the browser's default behavior and allow your code to run instead. Without them, the browser would otherwise navigate away from your page and open the files the user dropped into the browser window.

Check out Custom drag-and-drop for a live demonstration.

What about directories? #

Unfortunately, today there isn't a good way to access a directory.

The webkitdirectory attribute on the <input type="file"> element allows the user to choose a directory or directories. It's supported in most major browsers except for Firefox for Android.

If drag-and-drop is enabled, a user may try to drag a directory into the drop zone. When the drop event is fired, it will include a File object for the directory, but does not provide access any of the files within the directory.

Read file metadata #

The File object contains metadata about the file. Most browsers provide the file name, the size of the file, and the MIME type, though depending on the platform, different browsers may provide different, or additional information.

function getMetadataForFileList(fileList) {
  for (const file of fileList) {
    // Not supported in Safari for iOS.
    const name = file.name ? file.name : 'NOT SUPPORTED';
    // Not supported in Firefox for Android or Opera for Android.
    const type = file.type ? file.type : 'NOT SUPPORTED';
    // Unknown cross-browser support.
    const size = file.size ? file.size : 'NOT SUPPORTED';
    console.log({file, name, type, size});
  }
}

You can see this in action in the input-type-file demo.

Read a file's content #

To read a file, use FileReader, which enables you to read the content of a File object into memory. You can instruct FileReader to read a file as an array buffer, a data URL, or text.

function readImage(file) {
  // Check if the file is an image.
  if (file.type && !file.type.startsWith('image/')) {
    console.log('File is not an image.', file.type, file);
    return;
  }

  const reader = new FileReader();
  reader.addEventListener('load', (event) => {
    img.src = event.target.result;
  });
  reader.readAsDataURL(file);
}

The example above reads a File provided by the user, then converts it to a data URL, and uses that data URL to display the image in an img element. Check out the read-image-file demo to see how to verify that the user has selected an image file.

Monitor the progress of a file read #

When reading large files, it may be helpful to provide some UX to indicate how far the read has progressed. For that, use the progress event provided by FileReader. The progress event provides two properties, loaded (the amount read) and total (the amount to read).

function readFile(file) {
  const reader = new FileReader();
  reader.addEventListener('load', (event) => {
    const result = event.target.result;
    // Do something with result
  });

  reader.addEventListener('progress', (event) => {
    if (event.loaded && event.total) {
      const percent = (event.loaded / event.total) * 100;
      console.log(`Progress: ${Math.round(percent)}`);
    }
  });
  reader.readAsDataURL(file);
}

Hero image by Vincent Botta from Unsplash

Pete LePage on web.dev

How Chrome handles updates to the web app manifest

Updates on desktop Chrome #

Which properties will trigger an update? #

What happens when the display field is updated? #

Testing manifest updates #

References #

Updates on Chrome for Android #

Which properties will trigger an update? #

Testing manifest updates #

References #

Create an offline fallback page

An offline fallback page with a custom service worker #

Registering the service worker #

The service worker code #

The offline fallback page #

Demo #

Side note on making your app installable #

Side note on serving an offline fallback page with Workbox.js #

How to file a good browser bug

Verify it is a bug #

What's the correct behavior? #

Does it work in a different browser? #

Did it break in a recent release? #

Are others seeing the same problem? #

Has it been reported before? #

Report the bug #

Create a minimized test case #

Hosting a minified test case #

Filing your issue #

Provide a clear description and the steps required to reproduce the issue #

Bonus: Add a screenshot or screencast of the issue #

Include details of the environment #

Submit the bug #

How to define your install strategy

Why make your web app installable? #

Promoting installation of your PWA through the browser #

PWA as primary installable experience #

Prevent your PWA from cannibalizing your platform-specific app install rate #

Promoting installation of your PWA through an app store #

Promoting Lightweight Apps #

Providing a lightweight web experience #

Using JavaScript #

Using client hints #

Conclusion #

Persistent storage

Check if your site's storage has been marked as persistent #

When should I ask for persistent storage? #

Request persistent storage #

How is permission granted? #

Chrome and other Chromium-based browsers #

Firefox #

What storage is protected by persistent storage? #

How to turn off persistent storage #

Conclusion #

Thanks #

Storage for the web

What should I use? #

What about other storage mechanisms? #

How much can I store? #

How can I check how much storage is available? #

Inspect #

How to handle going over quota? #

IndexedDB #

Cache API #

How does eviction work? #

Bonus: Why use a wrapper for IndexedDB #

Conclusion #

Additional resources #

Thanks #

What does it take to be installable?

Install criteria #

How to provide your own in-app install experience

Promoting installation #

Listen for the beforeinstallprompt event #

In-app installation flow #

Detect when the PWA was successfully installed #

Detect how the PWA was launched #

Track how the PWA was launched #

Track when the display mode changes #

What happens when the `display` field is updated? #

Listen for the `beforeinstallprompt` event #

Using `any-hover` and `any-pointer` #