DocumentPictureInPicture: requestWindow() method

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:

disallowReturnToOpener Optional

A boolean value. When set to true, this option hints to the browser that it should not display a UI control that enables the user to return to the originating tab and close the Picture-in-Picture window. Defaults to false.

For example, in Chrome's implementation of this feature, the provided UI control is a "back to tab" button in the Picture-in-Picture window's top bar:

height Optional

A non-negative number representing the height to set for the Picture-in-Picture window's viewport, in pixels. Defaults to 0.

preferInitialWindowPlacement Optional

A boolean value, which defaults to false. When set to true, it causes the Picture-in-Picture window to always appear back at the position and size it initially opened at, when it is closed and then reopened. By contrast, if preferInitialWindowPlacement is false the Picture-in-Picture window's size and position will be remembered when closed and reopened — it will reopen at its previous position and size, for example as set by the user.

width Optional

A non-negative number representing the width to set for the Picture-in-Picture window's viewport, in pixels. Defaults to 0.

Return value

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

Exceptions

NotSupportedError DOMException

Thrown if the API has been explicitly disabled (for example via browser settings).

NotAllowedError DOMException

Thrown if:

• requestWindow() is not called from a top-level window object.
• requestWindow() is called from the window object of the Picture-in-Picture window (i.e., DocumentPictureInPicture.window).
• requestWindow() is called without transient activation.

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 with all options set
const pipWindow = await window.documentPictureInPicture.requestWindow({
  width: videoPlayer.clientWidth,
  height: videoPlayer.clientHeight,
  disallowReturnToOpener: true,
  preferInitialWindowPlacement: true,
});

// …

Specifications

Browser compatibility

See also

• Document Picture-in-Picture API
• Using the Document Picture-in-Picture API