Picture-in-Picture API
======================

The **Picture-in-Picture API** allow websites to create a floating, always-on-top video window. This allows users to continue consuming media while they interact with other sites or applications on their device.

**Note:** The Document Picture-in-Picture API extends the Picture-in-Picture API to allow the always-on-top window to be populated with *any* arbitrary HTML content, not just a video.

Interfaces
----------

`PictureInPictureWindow`

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

Instance methods
----------------

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

### Instance methods on the HTMLVideoElement interface

`HTMLVideoElement.requestPictureInPicture()`

Requests that the user agent enters the video into picture-in-picture mode

### Instance 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.

Instance properties
-------------------

The Picture-in-Picture API augments the `HTMLVideoElement`, `Document`, and `ShadowRoot` 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.

### Instance properties on the HTMLVideoElement interface

`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.

### Instance 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).

### Instance properties on the Document or ShadowRoot interfaces

`Document.pictureInPictureElement` / `ShadowRoot.pictureInPictureElement`

The `pictureInPictureElement` property tells you which `Element` is currently being displayed in the floating window (or in the shadow DOM). If this is `null`, the document (or shadow DOM) 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.

`leavepictureinpicture`

Sent to a `HTMLVideoElement` when it leaves picture-in-picture mode.

`resize`

Sent to a `PictureInPictureWindow` when it changes size.

Adding Controls
---------------

If media action handlers have been set via the Media Session API, then appropriate controls for those actions will be added by the browser to the picture-in-picture overlay. For example, if a `"nexttrack"` action has been set, then a skip button might be displayed in the picture-in-picture view. There is no support for adding custom HTML buttons or controls.

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 Permissions Policy. The fullscreen mode feature is identified by the string `"picture-in-picture"`, with a default allowlist 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.

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 picture-in-picture mode

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


```js
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 not `null`, it's the element that's currently in picture-in-picture mode, that is in a floating window. We call `document.exitPictureInPicture()` to bring the video back into its initial box.

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. We do it by calling `HTMLVideoElement.requestPictureInPicture()` on the `<video>` element.

Specifications
--------------

| Specification |
| --- |
| Picture-in-Picture # interface-picture-in-picture-window |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `HTMLVideoElement.requestPictureInPicture()`
* `HTMLVideoElement.disablePictureInPicture`
* `Document.pictureInPictureEnabled`
* `Document.exitPictureInPicture()`
* `Document.pictureInPictureElement`
* `:picture-in-picture`
* The Document Picture-in-Picture API