/Managing several displays with the Multi-Screen Window Placement API

Managing several displays with the Multi-Screen Window Placement API

Get information about connected displays and position windows relative to those displays.

Sep 14, 2020 Updated Sep 14, 2020

The Multi-Screen Window Placement API is part of the
capabilities project and is currently in
development. This post will be updated as the implementation progresses.

The Multi-Screen Window Placement API allows you to enumerate the
displays connected to your machine and to place windows on specific screens.

Suggested use cases

Examples of sites that may use this API include:

  • Multi-window graphics editors à la
    Gimp can place various
    editing tools in accurately positioned windows.
  • Virtual trading desks can show market trends in multiple windows any of which can be viewed in
    fullscreen mode.
  • Slideshow apps can show speaker notes on the internal primary screen and the presentation on an
    external projector.

Current status

Step Status
1. Create explainer Complete
2. Create initial draft of specification Complete
3. Gather feedback & iterate on design In progress
4. Origin trial In progress
5. Launch Not started

How to use the Multi-Screen Window Placement API

Enabling via chrome://flags

To experiment with the Multi-Screen Window Placement API locally, without an origin trial token,
enable the #enable-experimental-web-platform-features flag in chrome://flags.

Enabling support during the origin trial phase

Starting in Chrome 86, the Multi-Screen Window Placement API will be available as an origin
trial in Chrome. The origin trial is expected to end in Chrome 88 (February 24, 2021).

Origin trials allow you to try new features and give feedback on their
usability, practicality, and effectiveness to the web standards community. For
more information, see the Origin Trials Guide for Web Developers.
To sign up for this or another origin trial, visit the registration page.

Register for the origin trial

  1. Request a token for your origin.
  2. Add the token to your pages. There are two ways to do that:
    • Add an origin-trial <meta> tag to the head of each page. For example,
      this may look something like:
      <meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">
    • If you can configure your server, you can also add the token
      using an Origin-Trial HTTP header. The resulting response header should
      look something like:
      Origin-Trial: TOKEN_GOES_HERE

The problem

The time-tested approach to controlling windows,
Window.open(),
is unfortunately unaware of additional screens.
While some aspects of this API seem a little archaic, such as its
windowFeatures
DOMString parameter, it has nevertheless served us well over the years. To specify a window’s
position, you can pass the
coordinates as left and top (or screenX and screenY respectively) and pass the desired
size as
width and height (or innerWidth and innerHeight respectively). For example, to open a
400×300 window at 50 pixels from the left and 50 pixels from the top, this is the code that you
could use:

const popup = window.open(
"https://example.com/",
"My Popup",
"left=50,top=50,width=400,height=300"
);

You can get information about the current screen by looking at the
window.screen property, which
returns a Screen object. This is the
output on my MacBook Air 13″:

window.screen;

Like most people working in tech, I have had to adapt myself to the new work reality and set up
my personal home office. Mine looks like on the photo below (if you are interested, you can read the
full details about my setup).
The iPad next to my MacBook Air is connected to the laptop via
Sidecar, so whenever I need to, I can quickly turn the
iPad into a second screen.

School bench on two chairs. On top of the school bench are shoe boxes supporting a laptop and two iPads surrounding it.
A multi-screen setup.

If I want to take advantage of the bigger screen, I can put the popup from the
code sample above on to the
second screen. I do it like this:

popup.moveTo(2500, 50);

This is a rough guess, since there is no way to know the dimensions of the second
screen. The info from window.screen only covers the built-in screen, but not the iPad screen.
The reported width of the built-in screen was 1680 pixels, so moving to
2500 pixels might work to shift the window over to the iPad, since I happen to know that it is
located on the right of my MacBook Air. How can I do this in the general case? Turns out, there is a
better way than guessing. That way is the Multi-Screen Window Placement API.

Feature detection

To check if the Multi-Screen Window Placement API is supported, use:

if ("getScreens" in window) {
}

The window-placement permission

Before I can use the Multi-Screen Window Placement API, I must ask the user for permission to do so.
The new window-placement permission can be queried with the
Permissions API like so:

let granted = false;
try {
const { state } = await navigator.permissions.query({ name: "window-placement" });
granted = state === "granted";
} catch {
}

The browser
can
choose to show the permission prompt dynamically upon the first attempt to use any
of the methods of the new API.
Read on to learn more.

The isMultiScreen() method

To use the the Multi-Screen Window Placement API, I will first call the
Window.isMultiScreen() method. It returns a promise that resolves with either true or false,
depending on whether one or multiple screens are currently connected to the machine. For my setup,
it returns true.

await window.isMultiScreen();

The getScreens() method

Now that I know that the current setup is multi-screen, I can obtain more
information about the second screen using Window.getScreens(). It returns a promise
that resolves with an array of Screen objects. On my MacBook Air 13 with a connected iPad, this
returns an array of two Screen objects:

await window.getScreens();

Note how the value of left for the iPad starts at 1680, which is exactly the width of the
built-in display. This allows me to determine exactly how the screens are arranged logically (next
to each other, on top of each other, etc.). There is also data now for each screen to show whether
it is an internal one and whether it is a primary one.
Note that the built-in screen
is not necessarily the primary screen.
Both also have an id, which, if
persisted across browser sessions, allows for window arrangements to be restored.

The screenschange event

The only thing missing now is a way to detect when my screen setup changes. A new event,
screenschange, does exactly that: it fires whenever the screen constellation
is modified.
(Notice that “screens” is plural in the event name.)
It also fires when the resolution of one of the connected screens changes or when a
new or an existing screen is (physically or virtually in the case of Sidecar) plugged in or unplugged.

Note that you need to look up the new screen details asynchronously, the screenschange event
itself does not provide this data. This may change in the
future
. For now you
can look up the screen details by calling window.getScreens() as shown below.

window.addEventListener('screenschange', async (event) => {
console.log('I am there, but mostly useless', event);
const details = await window.getScreens();
});

New fullscreen options

Until now, you could request that elements be displayed in fullscreen mode via the aptly named
requestFullScreen()
method. The method takes an options parameter where you can pass
FullscreenOptions. So far, its only property has been
navigationUI.
The Multi-Screen Window Placement API adds a new screen property that allows you to determine
which screen to start the fullscreen view on. For example, if you want to make the primary screen fullscreen:

try {
const primaryScreen = (await getScreens()).filter((screen) => screen.primary)[0];
await document.body.requestFullscreen({ screen: primaryScreen });
} catch (err) {
console.error(err.name, err.message);
}

Polyfill

It is not possible to polyfill the Multi-Screen Window Placement API, but you
can shim its shape so you can code exclusively against the new API:

if (!("getScreens" in window)) {
window.getScreens = async () => [window.screen];
window.isMultiScreen = async () => false;
}

The other aspects of the API—the onscreenschange event and the screen property of the
FullscreenOptions—would simply never fire or silently be ignored respectively by non-supporting
browsers.

Demo

If you are anything like me, you keep a close eye on the development of the various cryptocurrencies.
(In reality I very much do not, but, for the sake of this article, just assume I do.) To
keep track of the cryptocurrencies that I own, I have developed a web app that allows me to watch
the markets in all life situations, such as from the comfort of my bed, where I have a decent
single-screen setup.

Massive TV screen at the end of a bed with the author's legs partly visible. On the screen, a fake crypto currency trading desk.
Relaxing and watching the markets.

This being about crypto, the markets can get hectic at any time. Should this happen, I can quickly
move over to my desk where I have a multi-screen setup. I can click on any currency’s window
and quickly see the full details in a fullscreen view on the opposite screen. Below is a recent
photo of me taken during the last YCY bloodbath.
It caught me completely off-guard and left me
with my hands on my face.

The author with his hands on his panicking face staring at the fake crypto currency trading desk.
Panicky, witnessing the YCY bloodbath.

You can play with the demo embedded below, or see its source code on glitch.

Security and permissions

The Chrome team has designed and implemented the Multi-Screen Window Placement API using the core
principles defined in Controlling Access to Powerful Web Platform Features,
including user control, transparency, and ergonomics. The Multi-Screen Window Placement API exposes
new information about the screens connected to a device, increasing the fingerprinting surface of
users, especially those with multiple screens consistently connected to their devices. As one
mitigation of this privacy concern, the exposed screen properties are limited to the minimum needed
for common placement use cases. User permission is required for sites to get multi-screen
information and place windows on other screens.

User control

The user is in full control of the exposure of their setup. They can accept or decline the
permission prompt, and revoke a previously granted permission via the site information feature in
the browser.

Transparency

The fact whether the permission to use the Multi-Screen Window Placement API has been granted is
exposed in the browser’s site information and is also queryable via the Permissions API.

Permission persistence

The browser persists permission grants. The permission can be revoked via the browser’s site
information.

Feedback

The Chrome team wants to hear about your experiences with the Multi-Screen Window Placement API.

Tell us about the API design

Is there something about the API that does not work like you expected? Or are there missing methods
or properties that you need to implement your idea? Have a question or comment on the security
model?

  • File a spec issue on the corresponding GitHub repo, or add your thoughts to an existing
    issue.

Report a problem with the implementation

Did you find a bug with Chrome’s implementation? Or is the implementation different from the spec?

  • File a bug at new.crbug.com. Be sure to include as much detail as you
    can, simple instructions for reproducing, and enter Blink>WindowDialog in the
    Components box. Glitch works great for sharing quick and easy repros.

Show support for the API

Are you planning to use the Multi-Screen Window Placement API? Your public support helps the Chrome
team to prioritize features and shows other browser vendors how critical it is to support them.

  • Share how you plan to use it on the WICG Discourse thread
  • Send a tweet to @ChromiumDev with the #WindowPlacement hashtag and let us know
    where and how you are using it.
  • Ask other browser vendors to implement the API.

Helpful links

Acknowledgements

The Multi-Screen Window Placement API spec was edited by
Victor Costan and
Joshua Bell. The API was implemented by
Mike Wasserman. This article was reviewed by
Joe Medley,
François Beaufort,
and Kayce Basques.
Thanks to Laura Torrent Puig for the photos.

Last updated: Sep 14, 2020


Improve article