Signatur
Beschreibung
Die schreibgeschützte Eigenschaft document.pictureInPictureElement liefert das Element, das in diesem Dokument aktuell in einem schwebenden Bild-im-Bild-Fenster läuft. Ist kein Element im PiP-Modus, ist der Wert null. Pro Dokument kann immer nur ein Element gleichzeitig im PiP-Modus sein.
Typische Einsatzfälle: Man prüft vor einem Aufruf von video.requestPictureInPicture(), ob bereits ein Video schwebt, baut einen Umschalt-Button (PiP ein/aus) oder synchronisiert die Oberfläche (z. B. einen Platzhalter „Video läuft im Bild-im-Bild-Fenster“) mit dem tatsächlichen Zustand.
Die Eigenschaft gehört zur Picture-in-Picture-API. Zum Verlassen des Modus dient document.exitPictureInPicture(); Zustandsänderungen meldet das Video über die Events enterpictureinpicture und leavepictureinpicture. Ob die Funktion überhaupt verfügbar ist, verrät document.pictureInPictureEnabled.
Auch innerhalb eines Shadow DOM ist die Eigenschaft über ShadowRoot.pictureInPictureElement verfügbar; auf document wird ein Element im Shadow Tree auf seinen Host umgeschrieben (retargeting).
Rückgabewert
HTMLVideoElement) oder null, wenn keines aktiv ist.Beispiele
Aktuellen PiP-Zustand abfragen
const pipElement = document.pictureInPictureElement;
if (pipElement) {
console.log('Im PiP-Modus:', pipElement.id);
} else {
console.log('Kein Video im Bild-im-Bild-Modus');
}Umschalt-Button für Bild-im-Bild
const video = document.querySelector('#player');
const button = document.querySelector('#pip-toggle');
// Button ausblenden, wenn PiP nicht unterstützt oder deaktiviert ist
if (!('pictureInPictureEnabled' in document) || !document.pictureInPictureEnabled) {
button.hidden = true;
}
button.addEventListener('click', async () => {
try {
if (document.pictureInPictureElement === video) {
await document.exitPictureInPicture();
} else {
// Muss aus einer Nutzergeste heraus aufgerufen werden
await video.requestPictureInPicture();
}
} catch (err) {
console.error('PiP fehlgeschlagen:', err.name, err.message);
}
});UI über Events synchron halten
const video = document.querySelector('#player');
const status = document.querySelector('#pip-status');
const updateStatus = () => {
const active = document.pictureInPictureElement === video;
status.textContent = active
? 'Video läuft im Bild-im-Bild-Fenster'
: '';
};
video.addEventListener('enterpictureinpicture', updateStatus);
video.addEventListener('leavepictureinpicture', updateStatus);PiP beim Verlassen der Seite beenden
window.addEventListener('pagehide', () => {
if (document.pictureInPictureElement) {
document.exitPictureInPicture().catch(() => {});
}
});// Wichtig · Fallstricke
- Browser-Unterstützung: Chromium-Browser und Safari unterstützen die API; Firefox bietet zwar ein eigenes PiP-Overlay, implementiert die Web-API aber nicht – dort ist
document.pictureInPictureElementundefined. Daher immer per'pictureInPictureEnabled' in documentprüfen. - Die Eigenschaft ist schreibgeschützt; eine Zuweisung hat keine Wirkung (im Strict Mode kein Fehler, da nur Getter – Zuweisung wird still ignoriert bzw. wirft
TypeErrorim Strict Mode). - Nur
<video>-Elemente können über diese API in den PiP-Modus. Für beliebige HTML-Inhalte gibt es die separate Document Picture-in-Picture API (window.documentPictureInPicture, nur Chromium) – deren Fenster wird nicht überpictureInPictureElementgemeldet. - Safari kennt zusätzlich das ältere, proprietäre
video.webkitPresentationMode; in manchen Versionen ist ein Fallback darauf sinnvoll. requestPictureInPicture()erfordert eine Nutzeraktivierung und kann durch die Permissions-Policypicture-in-picture(z. B. in iframes) blockiert werden.