DocumentPictureInPicture: requestWindow() method
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
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
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-levelwindow
object.requestWindow()
is called from thewindow
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
andwidth
are set, or ifheight
andwidth
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 # dom-documentpictureinpicture-requestwindow |
Browser compatibility
BCD tables only load in the browser