HTMLVideoElement: requestPictureInPicture() method

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

The HTMLVideoElement method requestPictureInPicture() issues an asynchronous request to display the video in picture-in-picture mode.

It's not guaranteed that the video will be put into picture-in-picture. If permission to enter that mode is granted, the returned Promise will resolve and the video will receive an enterpictureinpicture event to let it know that it's now in picture-in-picture.

Syntax

requestPictureInPicture()

Parameters

None.

Return value

A Promise that will resolve to a PictureInPictureWindow object that can be used to listen when a user will resize that floating window.

Exceptions

NotSupportedError DOMException

Thrown if the feature is not supported (for example, disabled by a user preference or by a platform limitation).

SecurityError DOMException

Thrown if the feature is blocked by a Permissions Policy.

InvalidStateError DOMException

Thrown if the video element's readState is HAVE_NOTHING, or if the video element has no video track, or if the video element's disablePictureInPicture attribute is true.

NotAllowedError DOMException

Thrown if document.pictureInPictureElement is null and the document does not have transient activation.

Security

Transient user activation is required. The user has to interact with the page or a UI element for this feature to work.

Examples

This example requests that the video enters Picture-in-Picture mode, and sets an event listener to handle the floating window resizing.

js
function enterPictureInPicture() {
  videoElement.requestPictureInPicture().then((pictureInPictureWindow) => {
    pictureInPictureWindow.addEventListener("resize", () =>
      onPipWindowResize(),
    );
  });
}