manifest: launch_handler support

manifest: launch_handler — The launch_handler member’s client_mode sub-field controls how an installed PWA is launched: whether it reuses an existing app window or opens a new one, and whether that window is navigated to the launch’s target URL.

Browser & ecosystem support

• Legend
• Yes
• Partial
• Flag
• No
• Unknown

Browser / Platform	Support	Versions	Confidence	Source	Notes
Chrome (Desktop)	Yes	110	high	source	—
Chrome (Android)	Yes	110	high	source	1
Edge (Desktop)	Yes	110	high	source	2
Firefox (Desktop)	No	—	high	source	3
Firefox (Android)	No	—	high	source	45
Safari (macOS)	No	—	high	source	6
Safari (iOS)	No	—	high	source	78
Samsung Internet	Yes	21.0	high	source	9
WebView (Android)	Yes	110	high	source	10

1. Derived by browser-compat-data mirroring from Chrome.
2. Derived by browser-compat-data mirroring from Chrome.
3. No Firefox support is recorded in browser-compat-data.
4. No Firefox for Android support is recorded in browser-compat-data.
5. Derived by browser-compat-data mirroring from Firefox.
6. No Safari support is recorded in browser-compat-data.
7. No Safari on iOS support is recorded in browser-compat-data.
8. Derived by browser-compat-data mirroring from Safari.
9. Derived by browser-compat-data mirroring from Chrome Android.
10. Derived by browser-compat-data mirroring from Chrome Android.

Source data: /compatibility/manifest-launch-handler.json · Global usage: 72 % (StatCounter 2026-05)

Source: spec · MDN · Last verified 2026-10-03 · Confidence: high (computed from sources)

Setting client_mode

Per Chrome for Developers, launch_handler has one sub-field, client_mode, and defaults to {"client_mode": "auto"} when unspecified:

{
  "launch_handler": {
    "client_mode": "navigate-new"
  }
}

Per MDN, the allowed client_mode values are navigate-new (always open a new client), navigate-existing (focus and navigate an existing client, falling back to navigate-new if none is open), focus-existing (focus an existing client without navigating it, again falling back to navigate-new if none is open), and auto (the user agent picks whichever behavior fits the platform).

Reading the launch target with LaunchQueue

Per MDN, whichever client_mode is used, the launch’s target URL is made available through window.launchQueue for custom navigation handling:

if ("launchQueue" in window) {
  window.launchQueue.setConsumer((launchParams) => {
    if (launchParams.targetURL) {
      const url = new URL(launchParams.targetURL);
      // Route the already-open app window to the launched URL yourself.
      history.pushState(null, "", url.pathname + url.search);
    }
  });
}

Detecting support and falling back

Feature-detect "launchQueue" in window before registering a consumer. When launchQueue is unavailable, the fallback below routes from the page’s current location:

if ("launchQueue" in window) {
  window.launchQueue.setConsumer((launchParams) => {
    if (launchParams.targetURL) {
      route(new URL(launchParams.targetURL));
    }
  });
} else {
  // LaunchQueue is unavailable — fall back to the current page URL.
  route(new URL(location.href));
}

What goes wrong

• Firefox and Safari do not implement launch_handler, per the compatibility data above — always provide a fallback that works from location alone.
• navigate-existing and focus-existing both fall back to navigate-new behavior when no client is already open, per MDN — do not assume an existing window exists.
• Feature-detect "launchQueue" in window before calling setConsumer().
• navigate-new and navigate-existing navigate a client to the target URL; focus-existing does not, so handle launchParams.targetURL when that mode should route the focused client to the target.

Where to go next

• manifest: file_handlers support — another manifest member that delivers launch data through window.launchQueue.
• manifest: share_target support — a related manifest member for handling incoming data on launch.

← Back to the Compatibility explorer.