The Document Picture-in-Picture API makes it possible to open an always-on-top window that can be populated with arbitrary HTML content — for example a video with custom controls or a set of streams showing the participants of a video conference call. It extends the earlier Picture-in-Picture API for
<video>, which specifically enables an HTML
<video> element to be put into an always-on-top window.
It is often helpful to have a different window available to a web app in addition to the main window in which the app is running. You might want to browse other windows while keeping specific app content in view, or you might want to give that content its own space while keeping the main app window freed up to display other content. You could handle this by just opening a regular new browser window, but this has two major issues:
- You have to handle sharing of state information between the two windows.
- The additional app window doesn't always stay on top, and can therefore get hidden by other windows.
To solve these problems, web browsers have introduced APIs allowing apps to spawn an always-on-top window that is part of the same session. The first recognized use case was keeping video content playing in a separate window so that the user can continue to consume it while looking at other content. This is handled using the Picture-in-Picture API for
<video>, which is directly used on a
<video> element to place it into the separate window.
However, this API has been found to be somewhat limiting — you can only put a single
<video> element into the always-on-top window, with minimal browser-generated controls. To provide more flexibility, the Document Picture-in-Picture API has been introduced. This allows any content to be placed in the always-on-top window for a wide range of use cases, including:
- An always-on-top custom video player showing one or multiple videos with custom controls and styling.
- A video conferencing system that allows the user to always see the other participant's streams, plus controls for presenting content, muting, ending calls, etc.
- Always-visible productivity tools such as timers, notes, to-do lists, messenger tools, etc.
- A separate window in which to keep additional content while the main app window is kept free of clutter. For example, you might have a action or roleplaying game running where you want to show the game controls, instructions, or lore in an additional window, keeping the main window free for displaying the game locations and map.
DocumentPictureInPicture object instance representing the always-on-top Picture-in-Picture window for the current document context is available via
Window.documentPictureInPicture. The Picture-in-Picture window is opened by calling the
DocumentPictureInPicture.requestWindow() method, which returns a
Promise that fulfills with the window's own
The Picture-in-Picture window is similar to a blank same-origin window opened via
Window.open(), with some differences:
- The Picture-in-Picture window floats on top of other windows.
- The Picture-in-Picture window never outlives the opening window.
- The Picture-in-Picture window cannot be navigated.
- The Picture-in-Picture window position cannot be set by the website.
Apart from that, you can manipulate the Picture-in-Picture window's
Window instance however you want, for example appending the content you want to display there onto its DOM, and copying stylesheets to it so that the appended content will be styled the same way as when it is in the main window. You can also close the Picture-in-Picture window (by clicking the browser-provided control, or by running
Window.close() on it), and then react to it closing using the standard
pagehide. When it closes, you'll want to put the content it was showing back into the main app window.
See Using the Document Picture-in-Picture API for a detailed usage guide.
|Document Picture-in-Picture Specification |
BCD tables only load in the browser