DocumentPictureInPicture: requestWindow() method

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The requestWindow() method of the DocumentPictureInPicture interface opens the Picture-in-Picture window for the current main browsing context. It returns a Promise that fulfills with a Window instance representing the browsing context inside the Picture-in-Picture window.

The requestWindow() method requires transient activation, i.e. it must be invoked in response to a user action such as a mouse click or button press.

Syntax

requestWindow()
requestWindow(options)

Parameters

options Optional

An options object containing the following properties:

height: A non-negative number representing the height to set for the Picture-in-Picture window's viewport, in pixels. If options is not specified, the default value 0 is used.
width: A non-negative number representing the width to set for the Picture-in-Picture window's viewport, in pixels. If options is not specified, the default value 0 is used.

Note: If one of the options is specified, the other one must be too, otherwise an error is thrown. If both values are not specified, specified as 0, or set too large, the browser will clamp or ignore the values as appropriate to provide a reasonable user experience. The clamped size will vary depending on implementation, display size, and other factors.

Return value

A Promise that fulfills with a Window object instance representing the browsing context inside the Picture-in-Picture window.

Exceptions

NotAllowedError DOMException

Thrown if:

requestWindow() is invoked without transient activation.
The API has been explicitly disabled (for example via browser settings).
requestWindow() is called from the window object of the Picture-in-Picture window (i.e. DocumentPictureInPicture.window)

RangeError DOMException

Thrown if only one of height and width are set, or if height and width are set with negative values.

Examples

const videoPlayer = document.getElementById("player");

// ...

// Open a Picture-in-Picture window.
const pipWindow = await window.documentPictureInPicture.requestWindow({
  width: videoPlayer.clientWidth,
  height: videoPlayer.clientHeight,
});

// ...

Specifications

Specification
Document Picture-in-Picture Specification # dom-documentpictureinpicture-requestwindow

Browser compatibility

	Desktop						Mobile
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	WebView Android	Chrome Android	Firefox for Android	Opera Android	Safari on IOS	Samsung Internet
`requestWindow`	116	116	No	No	102	No	No	No	No	No	No	No

Docs

Docs4dev

Title here