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
andheight
properties, and anonresize
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 isfalse
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 whichElement
is currently being displayed in the floating window (or in the shadow DOM). If this isnull
, 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