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.
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 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.
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 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).
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.
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 fullscreen 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 picture-in-picture 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 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