# Manifest launch_handler: controlling how an installed app launches

> How the launch_handler manifest member's client_mode controls whether launching an installed web app focuses or navigates an existing window or opens a new one, its four values, their fallback behavior, and its current experimental, non-Baseline browser support.

**In one line:** `launch_handler` defines a `client_mode` that tells the browser whether launching an installed app should focus or navigate an existing app window, or open the app in a new one.

## Syntax

```json
{
  "launch_handler": {
    "client_mode": "focus-existing"
  }
}
```

`client_mode` also accepts an array of strings; the first valid value in the array is used:

```json
{
  "launch_handler": {
    "client_mode": ["focus-existing", "auto"]
  }
}
```

## `client_mode` values

| Value | Meaning |
|---|---|
| `auto` | The user agent decides the loading context appropriate for the platform (for example, `navigate-existing` may make more sense on mobile, and `navigate-new` on desktop). This is also the default used if all provided values are invalid. |
| `focus-existing` | If the app is already loaded in a web app client, that instance is brought into focus but not navigated to the launch target URL. The target URL is made available via `Window.launchQueue` for custom navigation handling. |
| `navigate-existing` | If the app is already loaded, the existing client is brought into focus **and** navigated to the launch target URL. The target URL is also exposed via `Window.launchQueue`. |
| `navigate-new` | The app is loaded inside a new web app client instance. The target URL is made available via `Window.launchQueue`. |

## Fallback behavior

- If a `client_mode` string (or every value in an array of strings) is invalid, the behavior falls back to `auto`.
- Both `focus-existing` and `navigate-existing` fall back to `navigate-new` behavior when no existing app instance is currently loaded.

## Browser support

`launch_handler` is marked experimental and has limited availability — it does not work in some widely-used browsers and is not part of Baseline. Check the current browser compatibility data before relying on it in production.

## Practical checklist

- [ ] Pick a `client_mode` (or fallback array) matching how the app should behave when launched while already open.
- [ ] Read the target URL from `Window.launchQueue` in all modes that expose one.
- [ ] Feature-detect and verify current browser support before depending on non-`auto` behavior in production.

## Cross-references

- [Manifest start_url](/reference/manifest/start-url/) — another manifest member that influences what URL an installed app opens