Manifest member in Manifest
launch_handler manifest member
Published
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.
Member
Section titled “Member”| 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:
autoleaves the choice to the browser. Chromium picksnavigate-existingon Android, where one app instance is the norm, andnavigate-newon desktop.navigate-newopens a new app window at the launch URL.navigate-existingbrings the most recently used window to the front and navigates it to the launch URL.focus-existingbrings that window to the front and does not navigate. The page receives the launch URL throughlaunchQueueand 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.
Examples
Section titled “Examples”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.
See also
Section titled “See also”- file_handlers manifest member
- protocol_handlers manifest member
- share_target manifest member
- start_url manifest member
- Web App Launch Handler API: launch_handler member (wicg.github.io)
- Control how your app is launched (developer.chrome.com)
- LaunchQueue (developer.mozilla.org)
Specifications
| Specification | Status |
|---|---|
| manifest: launch_handler | WICG draft |
- 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 |
- Derived by browser-compat-data mirroring from Chrome.
- Derived by browser-compat-data mirroring from Chrome.
- No Firefox support is recorded in browser-compat-data.
- No Firefox for Android support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Firefox.
- No Safari support is recorded in browser-compat-data.
- No Safari on iOS support is recorded in browser-compat-data.
- Derived by browser-compat-data mirroring from Safari.
- Derived by browser-compat-data mirroring from Chrome Android.
- Derived by browser-compat-data mirroring from Chrome Android.