<picture-in-picture>

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.

API documentation • Demo

Install

$ npm install --save @georapbox/picture-in-picture-element

Usage

Script

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';

Markup

<picture-in-picture>
  <video src="assets/bigbuckbunny.mp4" controls></video>
</picture-in-picture>

Style

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.

API

Properties

| Name | Reflects | Type | Required | Description | | ---- | -------- | ---- | -------- |----------- | | pipButtonTitlepip-button-title | ✓ | String | - | The title attribute of the the picture-in-picture button. |

Slots

| Name | Description | | ---- | ----------- | | (default) | Un-named slot for the HTMLVideoElement. | | pip-button-label | The content of the picture-in-picture button. |

Slots usage examples

<picture-in-picture>
  <video src="assets/bigbuckbunny.mp4" controls></video>

  <span slot="pip-button-label">Enter Picture-in-Picture mode</span>
</picture-in-picture>

CSS Parts

| Name | Description | | ---- | ----------- | | pip-button | The picture-in-picture button. |

Events

| 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 } |

Changelog

For API updates and breaking changes, check the CHANGELOG.

License

The MIT License (MIT)