A custom element that offers a declarative interface to the Picture-in-Picture API. It wraps an HTMLVideoElement
and if Picture-in-Picture API is supported, it displays a button to toggle picture-in-picture mode. If the API is not supported, the button will remain hidden.
$ npm install --save @georapbox/picture-in-picture-element
import { PictureInPicture } from './node_modules/@georapbox/picture-in-picture-element/dist/picture-in-picture.js';
// Manually define the element.
PictureInPicture.defineCustomElement();
Alternatively, you can import the automatically defined custom element.
import './node_modules/@georapbox/picture-in-picture-element/dist/picture-in-picture-defined.js';
<picture-in-picture>
<video src="assets/bigbuckbunny.mp4" controls></video>
</picture-in-picture>
By default, the component comes with the bare minimum styles to remain as less opinionated as possible. However, you can style the various elements of the component using the ::part()
CSS pseudo-elements provided for this purpose.
Name | Reflects | Type | Required | Description |
---|---|---|---|---|
pipButtonTitle pip-button-title |
✓ | String | - | The title attribute of the the picture-in-picture button. |
Name | Description |
---|---|
(default) | Un-named slot for the HTMLVideoElement . |
pip-button-label |
The content of the picture-in-picture button. |
<picture-in-picture>
<video src="assets/bigbuckbunny.mp4" controls></video>
<span slot="pip-button-label">Enter Picture-in-Picture mode</span>
</picture-in-picture>
Name | Description |
---|---|
pip-button |
The picture-in-picture button. |
Name | Description | Event Detail |
---|---|---|
picture-in-picture:enter |
Emitted when the HTMLVideoElement enters picture-in-picture mode successfully. |
{ videoElement: HTMLVideoElement, pipButton: HTMLButtonElement } |
picture-in-picture:leave |
Emitted when the HTMLVideoElement leaves picture-in-picture mode successfully. |
{ videoElement: HTMLVideoElement, pipButton: HTMLButtonElement } |
picture-in-picture:resize |
Emitted when the floating video window has been resized. | { width: Number, height: Number } |
picture-in-picture:error |
Emitted when an error occurs. An error might occur while requesting to enter or leave picture-in-picture mode because the HTMLVideoElement has disablePictureInPicture attribute or because video's metadata have not been loaded yet. |
{ error: DOMException } |
For API updates and breaking changes, check the CHANGELOG.