# PWAs on ChromeOS (launcher and shelf)

> How an installed PWA fits into ChromeOS: launcher and shelf entries, badging, Share Target, and file handling, each with feature detection and a fallback.

On ChromeOS an installed PWA is listed in the launcher next to Android and Linux apps,
can be pinned to the shelf, and opts into OS integration (a badge on its shelf icon, Web
Share and Share Target, file handling, right-click shortcuts) through the same manifest
members and capability APIs that Chrome uses on Windows, macOS, and Linux.

## How it works

ChromeOS runs the desktop Chrome browser, so the install path and the installed window are
Chrome's; what ChromeOS adds is where the app appears afterwards and which system surfaces
(launcher, shelf, the "Open with" list, the share sheet) it can plug into.

### Installing from Chrome

Google's ChromeOS developer documentation asks for a manifest that supplies the name, icon,
`start_url`, and `display` mode, plus a service worker that handles `fetch` and can serve
`start_url` offline
([Powerful PWAs](https://developers.google.com/chromeos/app-development/learn/powerful-pwas),
developers.google.com). With that in place, Chrome on a Chromebook offers the same two
paths as Chrome on other desktops (English UI): an **Install** button at the right end of
the address bar on sites that qualify, or the three-dot **More** menu, then **Cast, save,
and share**, then **Install page as app...**
([Chrome Help](https://support.google.com/chromebook/answer/9658361)). The installed app
appears "along-side other installed apps, like in the taskbar, launcher, desktop, and app
switcher", in Google's words; on ChromeOS the taskbar is the shelf.

### Capability support on ChromeOS

Each integration is a separate manifest member or API, and each reached ChromeOS on its own
schedule:

- **Badging.** `navigator.setAppBadge()` on an installed app draws, in chromeos.dev's
  description, "a small circle on the app's home icon" on the shelf.
- **Web Share and Web Share Target.** `navigator.share()` opens the ChromeOS share sheet
  from any tab; a `share_target` member registers the installed app to receive links,
  text, or files from other apps. chromeos.dev advises that the `action` page work offline
  so a share never fails for lack of a network.
- **File handling.** A `file_handlers` member makes the installed app appear in the
  ChromeOS "Open with…" list for the declared MIME types and extensions; Chrome 102 and
  Edge 102 ship the member on desktop platforms including ChromeOS
  ([File Handling API](https://developer.chrome.com/docs/capabilities/web-apis/file-handling),
  developer.chrome.com). The files arrive through `window.launchQueue`.
- **App shortcuts.** The `shortcuts` member fills the icon's right-click menu in the
  launcher and on the shelf.
- **Stable identity.** From Chrome 96 the manifest `id` member identifies the app
  independently of `start_url`, and two PWAs from one origin can coexist when their
  manifests carry different `id` values (chromeos.dev, 2022-05-23).

The Google page is explicit that a capability stable in Chrome on Windows or macOS "can
sometimes be a multi-year process" to reach stable support on ChromeOS, so a ChromeOS
claim needs a ChromeOS check.

## Examples

Badging and file handling shipped separately and are detected separately; neither check
implies the other.

### Badging the shelf icon only where badges exist

Detect `setAppBadge` rather than assuming an installed ChromeOS app has it. Firefox has no
implementation, and on Chrome for Android 84 and later the same call succeeds but a badge
appears only for an installed app and only on launchers that support it (this site's
`badging-api` dataset).

```js
async function setLauncherBadge(count) {
  if (!('setAppBadge' in navigator)) {
    return false; // no badge surface here: show the count inside the app instead
  }
  if (count > 0) {
    await navigator.setAppBadge(count);
  } else {
    await navigator.clearAppBadge();
  }
  return true;
}
```

The function returns `false` when it did nothing, so the caller can render an in-app
counter on browsers without the API instead of silently dropping the signal.

### Receiving files from "Open with…"

The `file_handlers` member only takes effect once the app is installed, and `launchQueue`
exists only in browsers that implement the API, so the consumer is registered behind a
check and the ordinary file picker remains the fallback:

```js
if ('launchQueue' in window && 'files' in LaunchParams.prototype) {
  window.launchQueue.setConsumer(async (launchParams) => {
    if (!launchParams.files.length) return;
    for (const handle of launchParams.files) {
      const file = await handle.getFile();
      openDocument(file);
    }
  });
} else {
  document.querySelector('#open-file').hidden = false; // <input type="file"> path
}
```

The `'files' in LaunchParams.prototype` test is the one developer.chrome.com documents; a
bare `'launchQueue' in window` also matches browsers that use the queue for other launch
types.

## Observed behaviour

Uninstalling a PWA on a Chromebook is a launcher operation, and its data checkbox is worded
differently from the one Chrome shows on Windows and macOS.

:::observed
On ChromeOS (English UI), right-clicking the app's icon in the launcher shows **Uninstall**;
the confirmation dialog has a checkbox labelled "Also delete browsing data", and Chrome
Help warns that ticking it clears every piece of site data in Chrome, so the next visit
requires signing in again. The same dialog on Windows, macOS, and Linux labels the checkbox
"Also delete data from Chrome." (Chrome Help, read 2026-10).
:::

Because ChromeOS storage is the browser profile's storage, that checkbox removes the
service worker registration and Cache Storage for the origin as well, so the site loads as
a first visit afterwards.

## See also

- [Powerful PWAs](https://developers.google.com/chromeos/app-development/learn/powerful-pwas) (developers.google.com)
- [Features to take full advantage of PWA installation](https://chromeos.dev/en/posts/features-to-take-full-advantage-of-pwa-installation) (chromeos.dev)
- [File Handling API](https://developer.chrome.com/docs/capabilities/web-apis/file-handling) (developer.chrome.com)
- [Manifest file_handlers](/reference/manifest/file-handlers/)
- [Manifest shortcuts](/reference/manifest/shortcuts/)
- [Badging API: app icon badges for installed PWAs](/reference/installation/badging/)
- [PWAs on Chrome and Android (WebAPK, TWA)](/reference/platforms/chrome-android/)
- [PWAs on desktop](/reference/platforms/desktop/)