# Window Management API: placing windows across multiple screens

> How window.screen.isExtended and Window.getScreenDetails() expose multi-screen layout details, the window-management permission prompt, the secure-context requirement, and today's Chromium-only support per MDN.

**In one line:** The Window Management API lets a page discover the screens attached to a
user's device and open or move windows onto a specific one — `window.screen.isExtended`
reports whether more than one screen exists, and the permission-gated
`Window.getScreenDetails()` returns the details (position, size, orientation) of every
screen so windows can be placed precisely.

## `isExtended` vs `getScreenDetails()`

- **`window.screen.isExtended`** is a boolean on the existing `Screen` interface. Per MDN,
  it returns `true` if the device has multiple screens and `false` if not. Per MDN, only
  `getScreenDetails()` is documented as prompting for permission — `isExtended` is safe to
  check first when deciding whether to offer a multi-window layout at all.
- **`Window.getScreenDetails()`** is the API that actually delivers per-screen data. It
  returns a `Promise` that resolves to a `ScreenDetails` object listing every screen
  available to the device. Per MDN, calling it asks the user for permission to manage
  windows across their displays; the resulting `ScreenDetails.screens` array carries each
  screen's position and size so a caller can compute where to open a new window.

## The permission model

- Per MDN, calling `getScreenDetails()` requests permission; its status can be read
  without prompting via `navigator.permissions.query({ name: 'window-management' })`.
- Both `getScreenDetails()` and `isExtended` require a **secure context** (HTTPS or
  `localhost`), per MDN.
- Per MDN, a `window-management` Permissions-Policy that blocks the API makes
  `getScreenDetails()` reject with a `NotAllowedError`, and makes `isExtended` always
  report `false`.

## Placing a window on a chosen screen

```js
async function openOnSecondaryScreen(url) {
  if (!('getScreenDetails' in window)) {
    // Fallback: no multi-screen API — open a single window on the default screen.
    window.open(url, '_blank');
    return;
  }
  try {
    const screenDetails = await window.getScreenDetails();
    const target = screenDetails.screens.find((s) => s !== screenDetails.currentScreen)
      ?? screenDetails.screens[0];
    window.open(
      url,
      '_blank',
      `left=${target.availLeft},top=${target.availTop},width=${target.availWidth},height=${target.availHeight}`,
    );
  } catch (err) {
    // The user denied the permission prompt, or a Permissions-Policy blocked it.
    window.open(url, '_blank');
  }
}
```

## Feature detection and the fallback

Check `window.screen.isExtended` before offering a multi-window layout at all — it needs no
permission prompt — then feature-detect `getScreenDetails` itself before calling it, and
always fall back to a normal single-screen `window.open()` when either check fails:

```js
if (window.screen.isExtended && 'getScreenDetails' in window) {
  // Offer the "open across all screens" affordance.
} else {
  // Single screen, or the API is unavailable: behave as a normal single-window app.
}
```

## Browser & ecosystem support

Per MDN, the Window Management API is an **experimental** technology, not Baseline, because
it is not supported in all widely-used browsers. `getScreenDetails()` and `isExtended` ship
in Chrome and Edge; Firefox and Safari (including iOS Safari) do not implement either.

## Practical checklist

- [ ] Check `window.screen.isExtended` first — it needs no permission prompt and tells you
      whether a multi-window layout is even possible.
- [ ] Feature-detect `'getScreenDetails' in window` before calling it; it does not exist
      outside Chromium browsers.
- [ ] Wrap `getScreenDetails()` in `try`/`catch` — it rejects with `NotAllowedError` on
      denial or when a `window-management` Permissions-Policy blocks it.
- [ ] Always fall back to a plain `window.open()` on unsupported browsers or a rejected
      permission — never leave the multi-window path as the only option.
- [ ] Serve the page over HTTPS (or `localhost`); the API is unavailable outside secure
      contexts.

## Where to go next

- [display_override](/reference/manifest/display-override/)
- [Tabbed application mode](/reference/manifest/tabbed-display/)