Multi-Screen Window Placement API in JavaScript

The Multi-Screen Window Placement API (now standardized as the Window Management API) enables web applications to detect multiple displays connected to a user’s computer and accurately position windows across them. This article explains how the API works, how JavaScript queries display configurations, how to request the required permissions, and how to programmatically open and place windows on specific monitors.

The Limitations of Traditional Screen Management

Historically, JavaScript offered limited access to display information through the window.screen object. This object only provides data regarding the screen on which the current browser window is located. It cannot detect whether additional monitors are connected, nor can it determine the coordinates or resolutions of secondary displays. As a result, web applications could not reliably open new windows on designated secondary screens.

How the Window Management API Works

The Window Management API overcomes these limitations by exposing detailed information about all connected displays. It introduces asynchronous methods to query screen layouts and tracks changes when displays are plugged in, removed, or repositioned.

1. Requesting Permission

Because multi-monitor details can be used for device fingerprinting, the API requires explicit user permission. The permission name is window-management.

You can check and request access using window.getScreenDetails():

async function requestScreenAccess() {
  try {
    const screenDetails = await window.getScreenDetails();
    console.log("Access granted to screen details:", screenDetails);
    return screenDetails;
  } catch (error) {
    console.error("Permission denied or API unsupported:", error);
  }
}

2. Inspecting Screen Details

Once access is granted, the ScreenDetails object provides comprehensive properties:

Each ScreenDetailed object includes: * availLeft and availTop: The coordinates of the available area on the virtual desktop. * availWidth and availHeight: The dimensions available for application windows excluding OS taskbars or docks. * isPrimary: Indicates whether the monitor is the primary display. * isInternal: Indicates if the display is built into the device (such as a laptop screen). * label: A descriptive name of the display (e.g., “Internal Display” or external monitor model name).

3. Positioning a Window on a Specific Screen

To open a window on a specific monitor, retrieve the coordinate bounds from the target ScreenDetailed object and pass them to window.open() inside the windowFeatures string:

async function openWindowOnSecondaryScreen(url) {
  const screenDetails = await window.getScreenDetails();

  // Find a secondary screen
  const targetScreen = screenDetails.screens.find(
    (screen) => screen !== screenDetails.currentScreen
  );

  if (!targetScreen) {
    console.log("No secondary screen available.");
    return;
  }

  // Define position using the target screen's available coordinates
  const features = [
    `left=${targetScreen.availLeft}`,
    `top=${targetScreen.availTop}`,
    `width=${targetScreen.availWidth}`,
    `height=${targetScreen.availHeight}`,
    `menubar=no,toolbar=no,location=no,status=no`
  ].join(",");

  window.open(url, "_blank", features);
}

4. Listening for Display Changes

The API provides events to dynamically adapt when display setups change:

const screenDetails = await window.getScreenDetails();

screenDetails.addEventListener("screenschange", () => {
  console.log("Connected displays changed. Total screens:", screenDetails.screens.length);
});

screenDetails.addEventListener("currentscreenchange", () => {
  console.log("Window moved to:", screenDetails.currentScreen.label);
});

Primary Use Cases