API in Capabilities
Window Management API
Published Updated
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].
Syntax
Section titled “Syntax”window.screen.isExtended
window.getScreenDetails()
screenDetails.screensscreenDetails.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.
Members
Section titled “Members”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. |
Exceptions
Section titled “Exceptions”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.
Examples
Section titled “Examples”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.
See also
Section titled “See also”- display_override, the manifest member that sets which display modes an installed window may use
- Tabbed application mode and tab_strip
- PWAs on desktop
- Window Management: getScreenDetails() method (w3.org)
- Window Management: permission API integration (w3.org)
- Manage several displays with the Window Management API (developer.chrome.com)
- Chromium: window_screen_details.cc (chromium.googlesource.com)
Specifications
| Specification | Status |
|---|---|
| Window Management | W3C draft |
| Window Management: getScreenDetails() method | W3C draft |
| Window Management: ScreenDetailed interface | W3C draft |
| Window Management: extensions to FullscreenOptions | W3C draft |
- Legend
- Yes
- Partial
- Flag
- No
- Unknown
| Browser / Platform | Support | Versions | Confidence | Source | Notes |
|---|---|---|---|---|---|
| Chrome (Desktop)# | Yes | 100 | high | source | — |
| Chrome (Android)# | Yes | 100 | high | source | 1 |
| Edge (Desktop)# | Yes | 100 | 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 | 19.0 | high | source | 9 |
| WebView (Android)# | Yes | 100 | 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.