Skip to content

API in Capabilities

Window Management API

Published Updated

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

The Window Management API lets a page learn whether the device has more than one screen and where each one sits, then place windows on a specific screen. window.screen.isExtended answers the first question without a prompt, but it is a boolean and gives no count. window.getScreenDetails() requests the window-management permission and resolves with a ScreenDetails object. Its screens array holds one ScreenDetailed per display, with coordinates relative to the multi-screen origin. Use those coordinates in window.open() features, or pass a display to requestFullscreen({ screen }).

Chrome 100 ships getScreenDetails(), Screen.isExtended, and ScreenDetailed on desktop; Edge and Opera inherit the implementation. Chrome for Android exposes getScreenDetails() and isExtended, while BCD marks ScreenDetailed as unsupported there. Firefox and Safari have no implementation in any version (BCD api.Window.getScreenDetails). The interfaces require [SecureContext].

window.screen.isExtended
window.getScreenDetails()
screenDetails.screens
screenDetails.currentScreen
element.requestFullscreen({ screen: screenDetailed })

isExtended is a synchronous boolean on the existing Screen interface. getScreenDetails() returns Promise<ScreenDetails>; the same ScreenDetails object is returned on every call for a given Window, and it fires screenschange when a display is added or removed and currentscreenchange when the window moves to another display or its screen’s properties change. ScreenDetailed inherits from Screen, so width, height, availWidth, availHeight, colorDepth, and orientation are available alongside the members below.

getScreenDetails() takes no arguments. The objects it returns carry the following members; the only new option on an existing method is screen in FullscreenOptions, and setResizable(resizable) takes a boolean.

Member Type Required Description
ScreenDetails.screens FrozenArray<ScreenDetailed> Read-only Every screen, sorted by left then top. A new array each time the set changes.
ScreenDetails.currentScreen ScreenDetailed Read-only The screen the window is on; === to one entry of screens, so screens.find(s => s !== currentScreen) picks a screen other than the current one. That is not always the secondary display; check isPrimary when it matters.
ScreenDetailed.left, ScreenDetailed.top long Read-only Distance from the multi-screen origin to the screen’s left and top edge, in CSS pixels.
ScreenDetailed.availLeft, ScreenDetailed.availTop long Read-only Same, for the available area that excludes taskbars and docks. Use these as left/top in window.open() features.
ScreenDetailed.isPrimary boolean Read-only true for the display the OS designates as primary.
ScreenDetailed.isInternal boolean Read-only true for a built-in panel such as a laptop display, false for an external monitor.
ScreenDetailed.devicePixelRatio float Read-only Physical to CSS pixel ratio of that screen, which may differ from window.devicePixelRatio.
ScreenDetailed.label DOMString Read-only OS-supplied name, for example "Built-in Retina Display" or "DELL U2720Q"; may be empty.
FullscreenOptions.screen ScreenDetailed No Asks requestFullscreen() to move the window to that screen first. The browser may honour the user’s preference instead.

The specification defines one rejection name for getScreenDetails() and reuses it for the related minimize(), maximize(), restore(), and setResizable() methods (see the getScreenDetails() method (w3.org)).

Exception Condition
NotAllowedError The document is not allowed to use the window-management Permissions Policy feature (the default allowlist is 'self'); or the permission is not granted: the user denied or dismissed the prompt, or the call had no transient activation while the permission was still "prompt" (Chromium then makes no request and rejects). The window display-state methods also reject with it when the document is not an installed web app, lacks transient activation, or the OS refuses the change.

isExtended throws nothing and returns false when Permissions Policy blocks the feature, so a false means “single screen or not allowed to know”. FullscreenOptions.screen is an application preference that the browser may override with the user’s; the specification defines no rejection for it.

Use single-screen behaviour as the fallback. Firefox and Safari skip the multi-screen branch, as does Chrome when the user denies permission.

Opening a companion window on a secondary screen

Section titled “Opening a companion window on a secondary screen”

Check isExtended first (no prompt), call getScreenDetails() inside the click handler so the permission prompt is allowed, and fall back to a plain window.open() on any failure.

button.addEventListener("click", async () => {
const url = "/presenter-notes";
if (!("getScreenDetails" in window) || !window.screen.isExtended) {
window.open(url, "_blank", "popup");
return;
}
try {
const details = await window.getScreenDetails();
const target = details.screens.find((s) => s !== details.currentScreen) ?? details.currentScreen;
const features = `popup,left=${target.availLeft},top=${target.availTop},width=${target.availWidth},height=${target.availHeight}`;
window.open(url, "_blank", features);
} catch (err) {
console.warn(`${err.name}: ${err.message}`);
window.open(url, "_blank", "popup");
}
});

Because left and top in the features string are interpreted relative to the multi-screen origin once the permission is granted, negative coordinates are valid for a display placed left of or above the primary one.

Presenting fullscreen on the external display while notes stay on the laptop

Section titled “Presenting fullscreen on the external display while notes stay on the laptop”

Pass the chosen ScreenDetailed as FullscreenOptions.screen. The spec lets a successful cross-screen fullscreen request waive the activation requirement for one immediately following window.open(), which is what makes the notes window possible from the same click.

async function startPresentation(slides) {
if (!("getScreenDetails" in window)) {
return slides.requestFullscreen(); // current screen only
}
const details = await window.getScreenDetails();
const external = details.screens.find((s) => !s.isInternal);
if (!external) return slides.requestFullscreen();
await slides.requestFullscreen({ screen: external });
const notes = details.screens.find((s) => s.isInternal) ?? details.currentScreen;
window.open("/notes", "_blank", `popup,left=${notes.availLeft},top=${notes.availTop},width=800,height=600`);
}

When every screen reports isInternal: false (a desktop with two monitors) the code uses the current screen for the notes.

Reacting when a monitor is plugged in or removed

Section titled “Reacting when a monitor is plugged in or removed”

Listen for screenschange on the ScreenDetails object; window does not receive it. A new screens array replaces the previous one, which stays unchanged. Re-read it in the handler and close any companion window whose screen has gone.

async function watchScreens(onChange) {
if (!("getScreenDetails" in window)) {
window.screen.addEventListener("change", () => onChange([window.screen]));
return;
}
const details = await window.getScreenDetails();
onChange(details.screens);
details.addEventListener("screenschange", () => onChange(details.screens));
details.addEventListener("currentscreenchange", () => {
document.documentElement.style.setProperty("--dpr", details.currentScreen.devicePixelRatio);
});
}

The single-screen fallback listens to the change event the same specification adds to Screen, fired when a basic property of the window’s current screen (size, available size, color depth, orientation) changes. Pixel ratio is an advanced property, so a change there reaches ScreenDetailed.change and currentscreenchange but not Screen.change.

Specifications

SpecificationStatus
Window ManagementW3C draft
Window Management: getScreenDetails() methodW3C draft
Window Management: ScreenDetailed interfaceW3C draft
Window Management: extensions to FullscreenOptionsW3C draft
  • Legend
  • Yes
  • Partial
  • Flag
  • No
  • Unknown
Browser / PlatformSupportVersionsConfidenceSourceNotes
Chrome (Desktop)#Yes100highsource—
Chrome (Android)#Yes100highsource1
Edge (Desktop)#Yes100highsource2
Firefox (Desktop)#No—highsource3
Firefox (Android)#No—highsource45
Safari (macOS)#No—highsource6
Safari (iOS)#No—highsource78
Samsung Internet#Yes19.0highsource9
WebView (Android)#Yes100highsource10
  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/window-management.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)