PWA API Cheat Sheet¶

This page lists the JavaScript surface of Progressive Web Apps: every interface, method, option and event you touch when you register a service worker, cache responses, message clients, send push notifications, sync in the background, badge an icon, share content, handle launches or promote installation. Each entry gives the exact signature from the specification's Web IDL, the defaults and constraints that matter, the exceptions it throws, a one-line example and its browser support as of September 2026. It is a lookup page. The mechanisms, full examples and edge cases are on the linked topic pages, and the manifest has its own Manifest Cheat Sheet.

How to read this cheat sheet¶

Each API section follows the same pattern: a table of members with their Web IDL signature, what they return or do, and the constraints that trip people up, followed by one-line examples and a support row. The conventions are:

Version numbers are the first stable release with full support, taken from MDN's browser-compat-data (the September 24, 2026 release) and from browser release notes. "Chrome" includes Edge, Opera and Samsung Internet at the matching Chromium version unless a note says otherwise. "Safari iOS" means Safari and every other browser on iOS and iPadOS, because they all use WebKit.

Support at a glance¶

Support data as of September 2026. Check MDN and caniuse for live data.

Notes on the ⚠️ entries:

• iOS and iPadOS Push, Notifications and Badging work only in web apps added to the Home Screen, and only after the user grants notification permission from a user gesture inside that app. Since iOS 26, any site added with Open as Web App (on by default) is a web app, so no manifest or manifest display value is required. Safari tabs on iOS have no Notification object and no PushManager. See Web Push on iOS & Safari.
• Chrome desktop Web Share shipped on Windows and ChromeOS in Chrome 89 and on macOS in Chrome 128. Chrome on Linux has no share implementation. Firefox desktop has navigator.share() only behind the dom.webshare.enabled preference; Firefox for Android supports it from version 79 without files.
• Chrome desktop getInstalledRelatedApps() reported only Windows (UWP) apps from Chrome 85; Chrome 140 added detection of installed desktop web apps in the same scope. On Android, Chrome 80 detects Play Store apps and Chrome 84 detects installed PWAs.
• Firefox Declarative Web Push is implemented behind the dom.push.declarative.enabled preference and is off by default.
• Firefox display-mode: standalone parses from Firefox 57 but never matches on desktop, which has no standalone app window (the Windows taskbar web apps of Firefox 143+ are covered under minimal-ui below); Firefox for Android matches it from version 116.
• iOS display-mode is partial: in a Home Screen web app whose manifest says "display": "standalone", (display-mode: standalone) is false and (display-mode: fullscreen) is true (WebKit bug 264218), and minimal-ui never matches. A site added without a manifest reports browser. Check navigator.standalone === true first on Apple platforms, as described in Detecting Installed Apps.

Feature detection checks per API¶

Detect each API where you use it rather than sniffing user agents. Several APIs exist as objects even where they do nothing (Chrome on Linux resolves setAppBadge() without showing a badge, because Linux has no system badging API), so detection only tells you the call is safe, not that the user sees an effect.

One check per API (each is side-effect free and safe during page load; hasSW is "serviceWorker" in navigator):

The complete, commented detection module lives in A capability detection module on the Capabilities overview; use that as the single source rather than copying these checks.

Two detection traps: Notification.maxActions is undefined where actions are not supported (not 0), and "share" in navigator is true in Firefox desktop only when the preference is enabled. Detecting "onbeforeinstallprompt" in window tells you the browser can fire the event, not that it will. It fires only when the page meets the installability criteria and the app is not already installed.

ServiceWorkerContainer (navigator.serviceWorker)¶

navigator.serviceWorker is the page's handle on registrations and on the worker that controls it. It is [SecureContext] and exposed on Window and in workers. Chrome does not yet expose it inside workers; Firefox 133+ and Safari do.

RegistrationOptions:

register() rejections, from the specification's Register and Update algorithms:

One-liners:

const reg = await navigator.serviceWorker.register("/sw.js", { scope: "/", updateViaCache: "none" });
const readyReg = await navigator.serviceWorker.ready;           // active worker for this page
const isControlled = navigator.serviceWorker.controller !== null;
let refreshing = false; // guard: controllerchange can fire more than once (and reload loops with DevTools "Update on reload")
navigator.serviceWorker.addEventListener("controllerchange", () => {
  if (refreshing) return;
  refreshing = true;
  location.reload();
});
navigator.serviceWorker.onmessage = (e) => console.log("from SW", e.data); // also starts the queue

The full registration rules, scope resolution and the Service-Worker-Allowed header are on Registration & Scope.

ServiceWorkerRegistration¶

A ServiceWorkerRegistration binds a scope to up to three worker versions. You get one from register(), ready, getRegistration() or, inside the worker, self.registration. Exposed on W+Wk.

const reg = await navigator.serviceWorker.getRegistration();
reg?.addEventListener("updatefound", () => trackInstalling(reg.installing));
await reg?.update();                        // manual update check (e.g., on visibilitychange)
reg?.waiting?.postMessage({ type: "SKIP_WAITING" }); // ask the waiting worker to take over
const removed = await reg?.unregister();    // kill switch

Browsers also check for updates on their own: on every navigation to an in-scope page, on functional events such as push and sync and on subresource fetches only if no check ran in the last 24 hours, and when register() is called with a different script URL. There is no periodic 24-hour timer. Since Chrome 68 the main script is revalidated with the HTTP cache bypassed by default (updateViaCache: "imports"), so the old 24-hour HTTP cache cap matters only with updateViaCache: "all". The update flow and UI patterns are on Updating Service Workers.

ServiceWorker¶

A ServiceWorker object represents one worker version. You see it as registration.installing|waiting|active, navigator.serviceWorker.controller, event.source of a message event on the page, and self.serviceWorker inside the worker. Exposed on W+Wk.

stateDiagram-v2
    [*] --> parsed
    parsed --> installing
    installing --> installed: "install waitUntil resolved"
    installing --> redundant: "install failed"
    installed --> activating: "no clients or skipWaiting()"
    activating --> activated
    installed --> redundant: "replaced by newer worker"
    activated --> redundant: "replaced or unregistered"

self.serviceWorker (the worker's own ServiceWorker object, useful to read self.serviceWorker.state) ships in Chrome 79 and Safari 15.4 but not in Firefox. The lifecycle behind each state is explained on Lifecycle.

ServiceWorkerGlobalScope¶

self inside a service worker. It extends WorkerGlobalScope, so fetch(), caches, indexedDB, crypto, importScripts() (classic only), setTimeout() and navigator (a WorkerNavigator) are available. localStorage, sessionStorage, the DOM and synchronous XHR are not.

Service worker events¶

Two rules apply to every handler. First, add listeners synchronously during the worker's first evaluation: listeners added later (inside a promise or setTimeout) are not guaranteed to receive events, and Chrome warns about them. Second, the worker can be terminated whenever it has no pending events. Anything you need across events belongs in IndexedDB or Cache Storage, not in global variables.

self.addEventListener("install", (event) => event.waitUntil(precache()));
self.addEventListener("activate", (event) => event.waitUntil(Promise.all([deleteOldCaches(), self.clients.claim()])));
self.addEventListener("fetch", (event) => { if (shouldHandle(event.request)) event.respondWith(handle(event)); });
self.addEventListener("message", (event) => { if (event.data?.type === "SKIP_WAITING") self.skipWaiting(); });
self.addEventListener("push", (event) => event.waitUntil(showFromPush(event)));
self.addEventListener("notificationclick", (event) => event.waitUntil(openFromNotification(event)));

ExtendableEvent and waitUntil()¶

ExtendableEvent is the base class of every service worker event except messageerror. Its single method extends the event's lifetime.

Rules and errors:

• Calling waitUntil() after the event handler returned and after every previously added promise settled throws InvalidStateError. You may call it asynchronously as long as an earlier waitUntil() promise is still pending (asynchronous waitUntil(): Chrome 60, Firefox 53, Safari 11.1).
• In install, a rejected promise makes the new worker redundant. In activate, a rejection is ignored: the worker still becomes activated.
• In push, the promise must include showNotification() when you subscribed with userVisibleOnly: true. Otherwise Chrome shows a generic "This site has been updated in the background" notification, and Safari may revoke the subscription after repeated silent pushes.
• Browsers cap event duration. Chromium stops a worker 30 seconds after its last event settles, terminates a worker whose event takes more than 5 minutes, gives sync and periodicsync events at most 3 minutes, and gives push a shorter custom timeout (about 90 seconds). On timeout the worker is killed. Don't rely on long work finishing.

InstallEvent and Static Routing¶

InstallEvent extends ExtendableEvent with the Static Routing API, which lets the browser route matching requests without starting the worker. Chrome 123 and Safari 27 ship it; Firefox does not yet, although Mozilla's standards position is positive.

RouterRule is { condition, source }, both required:

The specification limits a worker to 1,024 conditions in total (nested ones included) and 10 levels of nesting.

self.addEventListener("install", (event) => {
  if (!event.addRoutes) return; // Firefox and older browsers: the fetch handler does everything
  event.waitUntil(event.addRoutes([
    { condition: { urlPattern: "/api/*", requestMethod: "GET" }, source: "network" },
    { condition: { urlPattern: "/assets/*" }, source: { cacheName: "static-v3" } },
    { condition: { requestMode: "navigate", runningStatus: "not-running" }, source: "race-network-and-fetch-handler" },
  ]));
});

Rule semantics, pitfalls such as new URLPattern() matching every origin, and the Resource Timing fields are on Static Routing API.

FetchEvent¶

FetchEvent is dispatched for every navigation within scope and every request from a controlled client, unless a static route handles it first. SW only.

respondWith() errors and response rules:

event.respondWith(caches.match(event.request).then((r) => r ?? fetch(event.request)));
event.respondWith((async () => (await event.preloadResponse) ?? fetch(event.request))());
event.waitUntil(event.handled.then(() => logTiming(event.request.url)));
if (event.request.mode === "navigate") { /* HTML document request */ }
if (event.request.destination === "image") { /* <img>, CSS images, favicon */ }

Useful Request properties in a handler: mode ("navigate", "cors", "no-cors", "same-origin"), destination, method, headers, cache, credentials, redirect, url, referrer, integrity, keepalive and signal. Strategies built on these are on Handling Fetch Events and Caching Strategies.

Clients, Client and WindowClient¶

self.clients is the worker's view of the documents and workers it can talk to. A client is a window (top-level document or iframe), a dedicated worker or a shared worker whose storage key matches the worker's. SW only for Clients; Client and WindowClient objects are only created inside the worker.

ClientQueryOptions:

Only notificationclick (and, in Chromium, backgroundfetchclick and payment events) grants the window interaction allowance that openWindow() and focus() need; the allowance lasts only a short, browser-defined time, so call them early in the handler rather than after slow network work. Calling either from push, message or fetch rejects with InvalidAccessError.

const windows = await self.clients.matchAll({ type: "window", includeUncontrolled: true });
const existing = windows.find((c) => new URL(c.url).pathname === "/inbox");
await (existing ? existing.focus() : self.clients.openWindow("/inbox")); // only in notificationclick
windows.forEach((c) => c.postMessage({ type: "CACHE_UPDATED", url: "/api/feed" }));
const client = await self.clients.get(event.clientId); // the page that issued this fetch

message events delivered to the worker are ExtendableMessageEvents:

Chromium stops an idle worker after 30 seconds, so a long-lived MessagePort does not keep it running. Request/response patterns, BroadcastChannel and the message queue are on Messaging & the Clients API.

CacheStorage and Cache¶

caches (a CacheStorage) is available on W+Wk in secure contexts. In an insecure context caches is undefined, which is the most common cause of "caches is not defined" on http:// staging hosts. Every cache is scoped to the storage key and shares the origin's quota with IndexedDB and OPFS.

CacheQueryOptions (all default to false): ignoreSearch ignores the query string of both URLs, ignoreMethod lets non-GET requests match, and ignoreVary skips the Vary header comparison. MultiCacheQueryOptions adds cacheName.

Any write can reject with QuotaExceededError. Matching never looks at Cache-Control, Expires or cookies: a stored response stays until you delete it.

const cache = await caches.open("static-v3");
await cache.addAll(["/", "/app.css", "/app.js"]);                    // atomic precache
await cache.put(request, response.clone());                         // clone before you return it
const hit = await caches.match("/offline.html", { cacheName: "static-v3" });
const withoutQuery = await cache.match(request, { ignoreSearch: true });
await Promise.all((await caches.keys()).filter((n) => n !== "static-v3").map((n) => caches.delete(n)));

The matching algorithm, opaque response padding and performance advice are on Cache Storage API. Strategy code is on Caching Strategies, and quotas are on Storage Quotas & Persistence.

NavigationPreloadManager¶

registration.navigationPreload lets the browser start the navigation request in parallel with booting the worker. Exposed on W+Wk; Chrome 59, Firefox 99, Safari 15.4.

The state belongs to the registration, not to the worker version, so it survives updates. Enable it in activate and always consume event.preloadResponse for navigations, otherwise you pay for a request you never use.

self.addEventListener("activate", (event) => {
  event.waitUntil(self.registration.navigationPreload?.enable());
});
self.addEventListener("fetch", (event) => {
  if (event.request.mode !== "navigate") return;
  event.respondWith((async () => {
    try {
      return (await event.preloadResponse) ?? (await fetch(event.request));
    } catch {
      return (await caches.match("/offline.html")) ?? Response.error();
    }
  })());
});

If your server returns different content for preload requests, send Vary: Service-Worker-Navigation-Preload. Details: Navigation Preload.

PushManager¶

registration.pushManager creates and reads push subscriptions. Exposed on W+Wk in secure contexts. Chrome 42, Firefox 44, Safari 16 on macOS and 16.4 on iOS and iPadOS (Home Screen web apps only).

PushSubscriptionOptionsInit:

subscribe() rejections:

PushSubscription¶

const reg = await navigator.serviceWorker.ready;
const sub = (await reg.pushManager.getSubscription())
  ?? (await reg.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: vapidKeyBytes }));
await fetch("/api/push/subscriptions", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(sub) });

JSON.stringify(sub) calls toJSON() for you. Server-side encryption, VAPID and push service responses are on The Web Push Protocol; the client flow is on Push Notifications.

PushEvent and PushMessageData¶

All the PushMessageData methods are synchronous: the payload is already decrypted when the event fires.

self.addEventListener("push", (event) => {
  let msg = {};
  try { msg = event.data?.json() ?? {}; } catch { /* malformed payload: still notify */ }
  event.waitUntil(self.registration.showNotification(msg.title ?? "New activity", {
    body: msg.body, tag: msg.tag, data: { url: msg.url ?? "/" },
  }));
});

pushsubscriptionchange¶

pushsubscriptionchange fires in the worker when the push service expires, rotates or revokes a subscription. The event is a PushSubscriptionChangeEvent with oldSubscription and newSubscription (both PushSubscription?).

newSubscription is often null, so the robust handler resubscribes with the options from oldSubscription (or from your stored VAPID key) and sends the result to your server, identifying the old record by its endpoint:

self.addEventListener("pushsubscriptionchange", (event) => {
  event.waitUntil((async () => {
    const options = event.oldSubscription?.options ?? { userVisibleOnly: true, applicationServerKey: await loadVapidKey() };
    const sub = event.newSubscription ?? (await self.registration.pushManager.subscribe(options));
    await fetch("/api/push/subscriptions", {
      method: "PUT", headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ old: event.oldSubscription?.endpoint ?? null, subscription: sub }),
    });
  })());
});

A worker can only resubscribe silently when permission is still granted; otherwise subscribe() rejects with NotAllowedError and the page has to ask again. Server-side, also treat 404 Not Found and 410 Gone from the push service as "delete this subscription".

Declarative Web Push (Safari)¶

Safari 18.4 on iOS and iPadOS and Safari 18.5 on macOS accept push messages that describe the notification directly, so the browser can show it without running JavaScript. The page subscribes through window.pushManager (a PushManager on Window that needs no service worker) or through a registration's pushManager as usual.

{
  "web_push": 8030,
  "notification": {
    "title": "New message from Ada",
    "body": "Are we still on for Friday?",
    "navigate": "https://example.com/inbox/42",
    "tag": "thread-42",
    "silent": false
  },
  "app_badge": 3,
  "mutable": true
}

Other browsers see the same bytes as an ordinary JSON payload, so a service worker that parses this shape serves every engine. Details and the silent-push rules are on Web Push on iOS & Safari.

Notification and NotificationEvent¶

The Notifications API has two halves: the Notification object (permission, and non-persistent notifications from a page) and registration.showNotification() (persistent notifications owned by the service worker, which is what a PWA uses). Notification is exposed on W+Wk; on iOS and iPadOS it exists only in Home Screen web apps.

NotificationOptions for showNotification(title, options):

NotificationAction is { action, title, icon?, navigate? }; action and title are required. showNotification() rejects with TypeError when permission isn't "granted", when the registration has no active worker, or for the invalid option combinations above.

self.addEventListener("notificationclick", (event) => {
  event.notification.close();
  const url = new URL(event.notification.data?.url ?? "/", self.location.origin).href;
  event.waitUntil((async () => {
    if (event.action === "archive") return fetch("/api/archive", { method: "POST", body: event.notification.tag });
    const tabs = await self.clients.matchAll({ type: "window", includeUncontrolled: true });
    const tab = tabs.find((c) => c.url === url);
    return tab ? tab.focus() : self.clients.openWindow(url);
  })());
});

registration.getNotifications({ tag }) returns the notifications still on screen, which is how you merge "3 new messages" into one. Everything about options, platforms and permission UX is on Notifications API.

Background Sync (SyncManager)¶

registration.sync defers work until the browser believes it is online. Exposed on W+Wk; Chromium 49+.

Chromium gives each sync event at most 3 minutes. If the waitUntil() promise rejects, the attempt counts as failed and is retried.

await (await navigator.serviceWorker.ready).sync.register("outbox");      // page, after writing to IndexedDB
self.addEventListener("sync", (e) => { if (e.tag === "outbox") e.waitUntil(flushOutbox({ final: e.lastChance })); });

Queue design and Workbox's BackgroundSyncPlugin are on Background Sync.

Periodic Background Sync (PeriodicSyncManager)¶

registration.periodicSync asks the browser to wake the worker at intervals. Chromium 80+, installed apps only. The periodic-background-sync permission is granted automatically when the origin has an installed app; otherwise register() rejects with NotAllowedError.

The periodicsync event (PeriodicSyncEvent) has a single tag attribute. Chromium fires at most once every 12 hours per origin, scaled by site engagement (never for sites with no engagement), only on a network the device has used before, and gives the event at most 3 minutes.

const { state } = await navigator.permissions.query({ name: "periodic-background-sync" });
if (state === "granted") await reg.periodicSync.register("refresh-feed", { minInterval: 24 * 60 * 60 * 1000 });
self.addEventListener("periodicsync", (e) => { if (e.tag === "refresh-feed") e.waitUntil(refreshFeedCache()); });

Frequency rules and testing are on Periodic Background Sync.

Background Fetch (BackgroundFetchManager)¶

registration.backgroundFetch hands large downloads (or uploads) to the browser's download manager, which shows progress UI and keeps going when every tab is closed. Chromium 74+.

BackgroundFetchOptions extends BackgroundFetchUIOptions: title (DOMString, default ""), icons (sequence<ImageResource>, default []) and downloadTotal (unsigned long long bytes, default 0 meaning unknown). downloadTotal is a hard cap: exceeding it fails the job with "download-total-exceeded".

fetch() rejects with TypeError for an empty request list, a no-cors request, a duplicate active id or no active worker; with QuotaExceededError when the job can't be stored; and with NotAllowedError when the background-fetch permission is denied. Three recent Chromium changes matter:

• Chrome 149 restricts background fetches started from a service worker by default (the temporary enterprise policy RestrictBackgroundFetchFromServiceWorkerEnabled switches the restriction off). Start jobs from a page, in response to a user action.
• CORS and Local Network Access: Chrome Platform Status lists enforcement for Chrome 154, after which cross-origin downloads need Access-Control-Allow-Origin like any fetch().
• In November 2025 an intent to deprecate and remove Background Fetch was posted to blink-dev, citing usage below 0.00002% of page loads. The API still ships in Chrome 154, but treat it as an enhancement with a plain-fetch() fallback.

A BackgroundFetchRecord has request and responseReady (Promise<Response>). In the worker, backgroundfetchsuccess and backgroundfetchfail are BackgroundFetchUpdateUIEvents with registration and updateUI({ title, icons }) (callable once, while the event is active); backgroundfetchabort and backgroundfetchclick are BackgroundFetchEvents with registration.

self.addEventListener("backgroundfetchsuccess", (event) => {
  event.waitUntil((async () => {
    const cache = await caches.open("episodes");
    const records = await event.registration.matchAll();
    await Promise.all(records.map(async (r) => cache.put(r.request, await r.responseReady)));
    await event.updateUI({ title: "Episode ready to play offline" });
  })());
});

Full lifecycle and fallbacks: Background Fetch.

StorageManager (navigator.storage)¶

navigator.storage is exposed on W+Wk in secure contexts. It covers quota, persistence and the origin private file system.

const { usage, quota } = await navigator.storage.estimate();
const durable = (await navigator.storage.persisted()) || (await navigator.storage.persist());
const root = await navigator.storage.getDirectory();
const handle = await root.getFileHandle("drafts.json", { create: true });

Storage Buckets (Chromium 122+) let one origin split its data into independently evictable buckets: navigator.storageBuckets.open(name, { persisted, durability, quota, expires }) returns a StorageBucket with its own indexedDB, caches, getDirectory(), estimate(), persist(), persisted(), setExpires() and expires(); keys() and delete(name) manage them. Bucket names must be lowercase letters, digits, - and _, starting with a letter or digit.

Quotas per engine, eviction and the Safari seven-day rule are on Storage Quotas & Persistence; OPFS is on Origin Private File System.

Cookie Store API¶

cookieStore gives pages and service workers asynchronous access to cookies (not HttpOnly ones). Chrome 87, Firefox 140 and Safari 18.4 ship cookieStore; only Chromium and Firefox ship service worker change subscriptions.

const session = await self.cookieStore.get("session");             // no document.cookie in workers
await self.registration.cookies?.subscribe([{ name: "session" }]); // Chromium, Firefox 140+
self.addEventListener("cookiechange", (e) => e.waitUntil(onSessionChange(e.changed, e.deleted)));

Content Index¶

registration.index (a ContentIndex) lists offline-available content (articles, podcasts) in the browser's own UI; Chrome for Android shows the entries on its Downloads page. Chrome on Android 84+ only; treat it as an experiment.

When the user removes an entry in browser UI, the worker gets contentdelete (ContentIndexEvent with id); delete the cached content there.

Badging API¶

The Badging API sets a badge on the installed app's icon (taskbar, Dock, shelf or Home Screen). It lives on navigator in pages and in workers, including service workers, so a push handler can update it. Chrome and Edge 81+ on Windows, macOS and ChromeOS (since Chrome 152, installed apps on macOS need notification permission for the badge to appear); Safari 17+ on macOS (Dock web apps); iOS and iPadOS 16.4+ (Home Screen web apps with notification permission). Firefox doesn't implement it.

Both reject with InvalidStateError when the document isn't fully active (for example, in the back/forward cache), with SecurityError from a frame that isn't same-origin with the top-level document, and with NotAllowedError when the browser requires notification permission and it isn't granted (the iOS model) or, in Chromium, inside a fenced frame. They resolve without effect where the platform has nowhere to draw a badge (Chrome on Linux). Chrome for Android does not expose the methods at all; Android draws its own notification dot on the app icon while a notification is showing. There is no getter: keep the count yourself.

await navigator.setAppBadge?.(unreadCount);                          // page or service worker
await navigator.clearAppBadge?.();
self.addEventListener("push", (e) => e.waitUntil((async () => {
  let unread; try { unread = e.data?.json().unread; } catch { /* malformed payload */ }
  // Pass a number: setAppBadge() with no argument (or undefined) shows a flag badge instead.
  await Promise.all([showFromPush(e), Number.isInteger(unread) ? navigator.setAppBadge?.(unread) : null]);
})()));

Platform behavior, persistence and iOS rules are on Badging API.

Web Share API¶

navigator.share() opens the operating system's share sheet. Window only, secure context, controlled by the web-share Permissions Policy (default 'self').

ShareData: title (USVString), text (USVString), url (USVString, resolved against the document URL; only http:/https: shareable) and files (sequence<File>). At least one known member must be present.

shareButton.addEventListener("click", async () => {
  const data = { title: document.title, url: location.href, files: preloadedFiles };
  try { await navigator.share(navigator.canShare?.(data) ? data : { title: data.title, url: data.url }); }
  catch (err) { if (err.name !== "AbortError") copyLinkFallback(); }
});

Support: Safari 12.1 (macOS) and 12.2 (iOS), files from Safari 14; Chrome on Android 61 (files 76); Chrome on Windows and ChromeOS 89, on macOS 128; Firefox for Android 79 (no files). Receiving shares is the manifest's share_target, covered on Web Share Target; sending is on Web Share API.

LaunchQueue and LaunchParams¶

window.launchQueue delivers launch data to an installed app: files opened through the manifest's file_handlers, and the target URL of launches handled by launch_handler. Chromium desktop only: Chrome 102 for files, Chrome 110 for targetURL.

if ("launchQueue" in window) {
  launchQueue.setConsumer(async ({ targetURL, files }) => {
    if (files.length) return openDocuments(await Promise.all(files.map((h) => h.getFile())));
    if (targetURL) router.navigate(new URL(targetURL).pathname); // focus-existing launches
  });
}

Set the consumer early (during module evaluation) so the first launch is not delayed. See File Handling and Protocol Handlers & Launch Handling.

Window Controls Overlay¶

With "display_override": ["window-controls-overlay"] in the manifest, Chromium desktop apps (Chrome and Edge 105+) can extend content into the title bar. navigator.windowControlsOverlay reports the free area.

CSS gets the same rectangle as env(titlebar-area-x), env(titlebar-area-y), env(titlebar-area-width) and env(titlebar-area-height), which are undefined while the overlay is off, so the env() fallback applies. Mark the draggable area with app-region: drag and every control inside it with app-region: no-drag. Chromium has long supported the prefixed -webkit-app-region (the only form MDN's compatibility data records), so declare both.

const wco = navigator.windowControlsOverlay;
wco?.addEventListener("geometrychange", ({ titlebarAreaRect, visible }) => layoutHeader(titlebarAreaRect, visible));
document.body.classList.toggle("wco", wco?.visible ?? false);

Layout recipes are on Window Controls Overlay.

BeforeInstallPromptEvent and appinstalled¶

Chromium fires beforeinstallprompt on window when the page meets the installability criteria and the app isn't installed. Call preventDefault() to suppress the automatic mini-infobar on Android and keep the event for your own button.

appinstalled is a plain Event fired on window after any successful install, including installs from the browser menu or address bar (Chrome 64 desktop, 57 Android). Use it for analytics and to hide your install button.

let deferred = null;
addEventListener("beforeinstallprompt", (e) => { e.preventDefault(); deferred = e; installButton.hidden = false; });
installButton.addEventListener("click", async () => {
  if (!deferred) return;
  const { outcome } = await deferred.prompt(); // synchronous from the click: keeps user activation
  deferred = null; installButton.hidden = true;
  analytics.track("install_prompt", { outcome });
});
addEventListener("appinstalled", () => analytics.track("app_installed"));

Full patterns, including iOS instructions, are on Install Prompts & Custom UI.

getInstalledRelatedApps()¶

navigator.getInstalledRelatedApps() tells a page whether the user has installed one of the apps listed in its manifest's related_applications. Chromium only; secure contexts and the top-level document only (in an iframe it rejects with InvalidStateError).

RelatedApplication is { platform, url, id, version }. Supported platforms and the back-link each needs:

Chrome only considers the first three entries of related_applications, and min_version and fingerprints are not implemented for this API.

const apps = (await navigator.getInstalledRelatedApps?.()) ?? [];
const hasPwa = apps.some((a) => a.platform === "webapp");
installButton.hidden = hasPwa; // the app is already installed on this device

See Detecting Installed Apps.

Web Install API (navigator.install())¶

The promise resolves with an empty WebInstallResult dictionary (reserved for future fields). Rejections from the explainer: NotAllowedError (no transient user activation, or blocked by the web-app-installation Permissions Policy), InvalidStateError (called outside the top-level frame or in a sandboxed context), TypeError (invalid arguments or URL scheme), AbortError (the user canceled the dialog), DataError (manifest fetch or parse failure, missing id, or manifestId mismatch) and NotFoundError (no document). The shape changed during the trials, so feature-detect with "install" in navigator and fall back to beforeinstallprompt. See Install Prompts & Custom UI.

Display mode and standalone detection¶

Installed apps run in a display mode chosen from the manifest's display_override and display. Read it with media queries, never with user-agent sniffing.

navigator.standalone (a non-standard boolean) is true in iOS and iPadOS Home Screen web apps and is the most reliable check there: check it first, because a Home Screen web app whose manifest says "display": "standalone" matches (display-mode: fullscreen) (WebKit bug 264218) and one without a manifest reports browser. Since Safari 17 the property also exists on macOS (false in tabs, true in Dock web apps), so its presence does not imply iOS; combine it with navigator.maxTouchPoints > 0 when you need the platform. Listen for changes with matchMedia(q).addEventListener("change", …): a user can move a Chromium app between a window and a tab.

const isInstalledContext = () =>
  ["standalone", "minimal-ui", "fullscreen", "window-controls-overlay"]
    .some((m) => matchMedia(`(display-mode: ${m})`).matches) || navigator.standalone === true;
matchMedia("(display-mode: standalone)").addEventListener("change", (e) => report(e.matches ? "app" : "tab"));

Manifest fields are summarized on the Manifest Cheat Sheet and explained on Display Modes.

Permission names for PWA features¶

navigator.permissions.query({ name }) reads a permission's state ("granted", "denied" or "prompt") without prompting, and its PermissionStatus fires change. Names relevant to PWAs:

Querying a name the engine doesn't know throws TypeError, so wrap query() in try/catch. Permission UX and Permissions Policy are on Permissions.

Other capability APIs PWAs use¶

These APIs are not PWA-specific, but installed apps lean on them. Each has a full page in the Device & OS Integration section.

Exceptions quick reference¶

Almost every PWA API reports failure as a rejected promise holding a DOMException (or a plain TypeError). Branch on err.name, never on the message text, which differs between engines.

A defensive wrapper for optional APIs keeps the call sites short:

/**
 * Call an optional PWA API and classify its failure.
 * Returns { ok: true, value } or { ok: false, reason } where reason is
 * "unsupported", "cancelled", "denied" or "failed".
 */
export async function tryFeature(fn) {
  try {
    return { ok: true, value: await fn() };
  } catch (err) {
    if (err instanceof ReferenceError || err?.name === "NotSupportedError") return { ok: false, reason: "unsupported", err };
    if (err?.name === "AbortError") return { ok: false, reason: "cancelled", err };
    if (err?.name === "NotAllowedError" || err?.name === "SecurityError") return { ok: false, reason: "denied", err };
    return { ok: false, reason: "failed", err };
  }
}

// Usage: const result = await tryFeature(() => navigator.share({ url: location.href }));

Further reading¶

On this site

• Core Building Blocks
• Lifecycle
• Handling Fetch Events
• Cache Storage API
• Push Notifications
• Manifest Cheat Sheet
• Glossary
• Resources & Specifications

External references

• Service Workers specification (W3C) and the editor's draft
• Push API specification
• Notifications API Standard (WHATWG)
• Badging API specification
• Web Share API specification
• MDN: Service Worker API
• MDN: Progressive web apps
• MDN browser-compat-data