Skip to content

Manifest member in Manifest

launch_handler manifest member

Published

Limited availabilityNot supported in Firefox (Desktop), Firefox (Android), Safari (macOS), Safari (iOS)WICG draft

The launch_handler manifest member controls how an installed web app reuses existing windows when launched from the OS launcher, a shortcut, a file association, a protocol link, or a share. Its single property, client_mode, selects whether to focus an open window, navigate it to the launch URL, or open a new window.

Chrome 110, Edge 110, Samsung Internet 21.0, and Android WebView 110 implement the member (BCD manifests.webapp.launch_handler). The compat data records no support in Firefox and Safari, so the member should not be relied on there. The launch URL reaches the page through window.launchQueue, which is what makes focus-existing usable at all.

Property Value
Type object with one property, client_mode, which is a string or an array of strings. Allowed values: auto, navigate-new, navigate-existing, focus-existing
Default auto. An absent member, a client_mode that is not a string or array, or an array in which no value is recognized all resolve to auto
Example value { "client_mode": ["focus-existing", "auto"] }

What each mode does when a window is already open:

  • auto leaves the choice to the browser. Chromium picks navigate-existing on Android, where one app instance is the norm, and navigate-new on desktop.
  • navigate-new opens a new app window at the launch URL.
  • navigate-existing brings the most recently used window to the front and navigates it to the launch URL.
  • focus-existing brings that window to the front and does not navigate. The page receives the launch URL through launchQueue and decides what to do with it.

When no window is open, focus-existing and navigate-existing behave as navigate-new. In an array, the browser takes the first value it recognizes, which is how a manifest can prefer focus-existing and still name auto for engines that add new modes later.

The Chromium parser rejects a non-object value with launch_handler value ignored, object expected., and an unknown string in client_mode produces client_mode value '<value>' ignored, unknown value. (manifest_parser.cc, ParseLaunchHandler). The invalid entry is skipped, not the whole member.

The launchQueue consumer handles launches routed to a window by focus-existing; the manifest setting takes one line.

Keeping a single editor window and routing launches into it

Section titled “Keeping a single editor window and routing launches into it”

Use focus-existing to keep a document editor in one window and switch to the requested document on each launch. The page consumes the launch URL and updates its own state.

{
"name": "Draft",
"start_url": "/",
"display": "standalone",
"launch_handler": { "client_mode": ["focus-existing", "auto"] },
"file_handlers": [
{ "action": "/open", "accept": { "text/markdown": [".md"] } }
]
}
if ('launchQueue' in window) {
window.launchQueue.setConsumer(async (launchParams) => {
const url = new URL(launchParams.targetURL);
if (launchParams.files.length > 0) {
const file = await launchParams.files[0].getFile();
await openDocument(file);
return;
}
const doc = url.searchParams.get('doc');
if (doc) await openDocumentById(doc);
});
} else {
// No launchQueue: the browser navigated normally, so read the URL directly.
const doc = new URL(location.href).searchParams.get('doc');
if (doc) await openDocumentById(doc);
}

The consumer runs once for the launch that created the window and again when a later launch is routed into it. launchParams.files is an array of FileSystemFileHandle objects when the launch came from a file association and empty otherwise.

Detecting the API and falling back to normal navigation

Section titled “Detecting the API and falling back to normal navigation”

Check for window.launchQueue before calling setConsumer(). The check confirms only that the interface exists, because MDN’s compatibility data tracks LaunchQueue and the launch_handler manifest member separately. Where launchQueue is absent, the helper reads location, which holds the launch URL only when the launch navigated the page; focus-existing does not navigate it. The helper gives the rest of the app a single callback for both cases.

export function onLaunch(handler) {
if ('launchQueue' in window) {
window.launchQueue.setConsumer((params) => handler(new URL(params.targetURL)));
} else {
handler(new URL(location.href));
}
}
onLaunch((url) => {
if (url.pathname === '/share') showShareSheet(url.searchParams);
});

Register the consumer before the first await in the module. Chromium queues launch parameters until a consumer exists. A consumer set late still fires, so delivery is delayed without losing parameters.

Preferring a fresh window on desktop and an existing one on mobile

Section titled “Preferring a fresh window on desktop and an existing one on mobile”

A news reader wants each desktop launch in its own window but a single window on a phone. auto already encodes that split in Chromium, so the manifest states it explicitly and lets the browser choose.

{
"launch_handler": { "client_mode": "auto" }
}

Writing auto is equivalent to omitting the member. Keeping it explicit gives you a place to change the mode when editing the manifest later.

Specifications

SpecificationStatus
manifest: launch_handlerWICG draft
  • Legend
  • Yes
  • Partial
  • Flag
  • No
  • Unknown
Browser / PlatformSupportVersionsConfidenceSourceNotes
Chrome (Desktop)#Yes110highsource—
Chrome (Android)#Yes110highsource1
Edge (Desktop)#Yes110highsource2
Firefox (Desktop)#No—highsource3
Firefox (Android)#No—highsource45
Safari (macOS)#No—highsource6
Safari (iOS)#No—highsource78
Samsung Internet#Yes21.0highsource9
WebView (Android)#Yes110highsource10
  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: 75 % (StatCounter 2026-09, CC BY-SA 4.0)

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