Web/API/Picture-in-Picture API

The Picture-in-Picture API allow websites to create a floating video window always on top of other windows so that users may continue consuming media while they interact with other content sites, or applications on their device.

Interfaces

PictureInPictureWindow: Represents the floating video window; contains width and height properties, and an onresize event handler property.

Methods

The Picture-in-Picture API adds methods to the HTMLVideoElement and Document interfaces to allow toggling of the floating video window.

Methods on the HTMLVideoElement interface

HTMLVideoElement.requestPictureInPicture(): Requests that the user agent enters the video into picture-in-picture mode

Methods on the Document interface

Document.exitPictureInPicture()

Requests that the user agent returns the element in picture-in-picture mode back into its original box.

Properties

The Picture-in-Picture API augments the HTMLVideoElement, Document, and DocumentOrShadowRoot interfaces with properties that can be used to determine if the floating video window mode is supported and available, if picture-in-picture mode is currently active, and which video is floating.

Properties on the HTMLVideoElement interface

HTMLVideoElement.autoPictureInPicture: The autoPictureInPicture property will automatically enter and leave the picture-in-picture mode for a video element when the user switches tab and/or applications.
HTMLVideoElement.disablePictureInPicture: The disablePictureInPicture property will provide a hint to the user agent to not suggest the picture-in-picture to users or to request it automatically.

Properties on the Document interface

Document.pictureInPictureEnabled

The pictureInPictureEnabled property tells you whether or not it is possible to engage picture-in-picture mode. This is false if picture-in-picture mode is not available for any reason (e.g. the "picture-in-picture" feature has been disallowed, or picture-in-picture mode is not supported).

Properties on the DocumentOrShadowRoot interface

DocumentOrShadowRoot.pictureInPictureElement: The pictureInPictureElement property tells you which Element is currently being displayed in the floating window. If this is null, the document has no node currently in picture-in-picture mode.

Events

The Picture-in-Picture API defines three events, which can be used to detect when picture-in-picture mode is toggled and when the floating video window is resized.

enterpictureinpicture: Sent to a HTMLVideoElement when it enters picture-in-picture mode. The associated event handler is HTMLVideoElement.onenterpictureinpicture
leavepictureinpicture: Sent to a HTMLVideoElement when it leaves picture-in-picture mode. The associated event handler is HTMLVideoElement.onleavepictureinpicture
resize: Sent to a PictureInPictureWindow when it changes size. The associated event handler is PictureInPictureWindow.onresize

Controlling styling

The :picture-in-picture CSS pseudo-class matches the video element currently in picture-in-picture mode, allowing you to configure your stylesheets to automatically adjust the size, style, or layout of content when a video switches back and forth between picture-in-picture and traditional presentation modes.

Controlling access

The availability of picture-in-picture mode can be controlled using Feature Policy. The full-screen mode feature is identified by the string "picture-in-picture", with a default allow-list value of "self", meaning that picture-in-picture mode is permitted in top-level document contexts, as well as to nested browsing contexts loaded from the same origin as the top-most document.

See Using Feature Policy to learn more about using Feature Policy to control access to an API.

Examples

In this example, a video is presented in a web page. Clicking the button below lets the user toggle the floating video window.

Toggling full-screen mode

This code is called by a click handler when the user clicks the "Toggle Picture-in-Picture" button:

function togglePictureInPicture() {
  if (document.pictureInPictureElement) {
      document.exitPictureInPicture();
  } else {
    if (document.pictureInPictureEnabled) {
      video.requestPictureInPicture(); 
    }
  }
}

This block starts by looking at the value of the document's pictureInPictureElement attribute. If the value is null, no video is in the floating window. so we can request a video to enter the picture-in-picture mode; otherwise, it's the element that's currently in picture-in-picture mode. Switching to picture-in-picture mode is done by calling HTMLVideoElement.requestPictureInPicture() on the <video> element.

If a video is in the floating window (pictureInPictureElement is not null), we call exitPictureInPicture() on the document to bring the video back into its initial box.

Specifications

Specification	Status
Picture-in-Picture API	Draft

Browser compatibility

`HTMLVideoElement.requestPictureInPicture`

No compatibility data found. Please contribute data for "api.HTMLVideoElement.requestPictureInPicture" (depth: 1) to the MDN compatibility data repository.

`HTMLVideoElement.autoPictureInPicture`

No compatibility data found. Please contribute data for "api.HTMLVideoElement.autoPictureInPicture" (depth: 1) to the MDN compatibility data repository.

`HTMLVideoElement.disablePictureInPicture`

No compatibility data found. Please contribute data for "api.HTMLVideoElement.disablePictureInPicture" (depth: 1) to the MDN compatibility data repository.

`Document.pictureInPictureEnabled`

No compatibility data found. Please contribute data for "api.Document.pictureInPictureEnabled" (depth: 1) to the MDN compatibility data repository.

`Document.exitPictureInPicture`

No compatibility data found. Please contribute data for "api.Document.exitPictureInPicture" (depth: 1) to the MDN compatibility data repository.

`DocumentOrShadowRoot.pictureInPictureElement`

No compatibility data found. Please contribute data for "api.DocumentOrShadowRoot.pictureInPictureElement" (depth: 1) to the MDN compatibility data repository.

`PictureInPictureWindow`

No compatibility data found. Please contribute data for "api.PictureInPictureWindow" (depth: 1) to the MDN compatibility data repository.