JavaScript Document pictureInPictureElement Property

What You’ll Learn

Document.pictureInPictureElement is a read-only instance property that returns the Element currently shown in picture-in-picture (PiP) mode, or null. Learn MDN’s exit helper, how it parallels fullscreenElement, video PiP workflows, and five examples with try-it labs.

Introduction

Picture-in-picture mode lets users watch a video in a small floating window while continuing to browse the page. When PiP is active, scripts need to know which element is playing in that window—that is what document.pictureInPictureElement provides.

MDN: the read-only property returns the Element that is currently being presented in picture-in-picture mode in this document, or null if picture-in-picture mode is not currently in use.

Related Document tutorials: fullscreenElement, hidden, activeElement, Document constructor.

Understanding Document.pictureInPictureElement

A read-only instance property on Document. Its value is the element in PiP mode, or null when PiP is off.

• Value — Element reference in PiP, or null (MDN).
• Read-only — assigning does not throw; the setter is ignored (MDN no-op).
• Null cases — no PiP active, or the PiP element belongs to an iframe (MDN).
• Typical element — often an HTMLVideoElement after requestPictureInPicture().
• Exit — pair with document.exitPictureInPicture() when truthy (MDN example).

📝 Syntax

document.pictureInPictureElement

Value

An Element object — or null when picture-in-picture mode is not in use for this document (MDN).

MDN example — exit PiP if active

function exitPictureInPicture() {
  if (document.pictureInPictureElement) {
    document.exitPictureInPicture();
  }
}

Check if PiP is active

const isPiP = document.pictureInPictureElement !== null;
console.log("PiP active?", isPiP);

⚖️ Presentation Mode Properties

Examples Gallery

Examples follow MDN Document: pictureInPictureElement. Try-it labs read the property safely; enter PiP from a user click where the browser supports it.

console.log(document.pictureInPictureElement);
// null when PiP is not active
console.log(document.pictureInPictureElement === null);

null
true

function exitPictureInPicture() {
  if (document.pictureInPictureElement) {
    document.exitPictureInPicture();
  }
}

exitPictureInPicture(); // no-op when null

(no error — exit skipped when PiP is off)

const el = document.pictureInPictureElement;
if (el) {
  console.log(el.nodeName); // often "VIDEO"
  console.log(el.id);
} else {
  console.log("No PiP element");
}

No PiP element

const video = document.querySelector("#player");

async function togglePiP() {
  if (document.pictureInPictureElement) {
    await document.exitPictureInPicture();
  } else if (document.pictureInPictureEnabled) {
    await video.requestPictureInPicture();
  }
  console.log(document.pictureInPictureElement);
}

After PiP starts: HTMLVideoElement
After exit: null

function updatePiPUI() {
  const active = document.pictureInPictureElement !== null;
  console.log("PiP active?", active);
}

document.addEventListener("enterpictureinpicture", updatePiPUI);
document.addEventListener("leavepictureinpicture", updatePiPUI);

PiP active? true  (on enter)
PiP active? false (on leave)

🚀 Common Use Cases

• Toggle PiP button — show “Exit PiP” when the property is not null.
• Custom close control — MDN-style exitPictureInPicture() wrapper.
• Analytics — log which video element entered PiP.
• Accessibility — announce PiP state changes to screen readers.
• Single PiP policy — ensure only one video uses PiP at a time.
• Debugging — verify PiP state during media player development.

📝 Notes

• MDN: Limited availability (not Baseline) — no Deprecated / Experimental / Non-standard banner.
• Assigning to the property is a no-op; it never throws, even in strict mode (MDN).
• Returns null for iframe PiP elements in the parent document (MDN).
• Pair with document.pictureInPictureEnabled before offering PiP controls.
• Related: fullscreenElement, hidden, Document constructor.

💡 Best Practices