JavaScript Document pictureInPictureEnabled Property

What You’ll Learn

Document.pictureInPictureEnabled is a read-only instance property that tells you whether picture-in-picture (PiP) mode is available for this document. Learn how to guard requestPictureInPicture(), how it differs from pictureInPictureElement, Permissions-Policy notes, and five examples with try-it labs.

Introduction

Before calling video.requestPictureInPicture(), it helps to know whether the browser will allow it. document.pictureInPictureEnabled answers that question with a simple true or false.

MDN: the read-only property indicates whether or not picture-in-picture mode is available. Picture-in-picture is available by default unless a Permissions-Policy turns it off. It pairs with pictureInPictureElement in the Picture-in-Picture API.

Related Document tutorials: pictureInPictureElement, fullscreenEnabled, Document constructor.

Understanding Document.pictureInPictureEnabled

A read-only instance property on Document that reports Picture-in-Picture API availability—not whether PiP is currently active.

• Value — true if a video can enter PiP via requestPictureInPicture(); otherwise false (MDN).
• Default — MDN: available by default unless a Permissions-Policy disables it.
• Lenient setter — assigning does not throw; the write is ignored (MDN).
• Pair with — check before requestPictureInPicture(); use pictureInPictureElement to see the active element.
• UI tip — hide or disable PiP buttons when the value is false.

📝 Syntax

document.pictureInPictureEnabled

Value

A boolean: true when picture-in-picture can be requested; false when it cannot (MDN).

MDN guard example

function requestPictureInPicture() {
  if (document.pictureInPictureEnabled) {
    videoElement.requestPictureInPicture();
  } else {
    console.log("Your browser cannot use picture-in-picture right now");
  }
}

⚖️ Picture-in-Picture Document Properties

Examples Gallery

Examples follow MDN Document: pictureInPictureEnabled. On most supporting browsers the value is true unless a policy blocks PiP.

console.log(document.pictureInPictureEnabled);
console.log("PiP available?", document.pictureInPictureEnabled === true);

true
PiP available? true

function requestPictureInPicture() {
  if (document.pictureInPictureEnabled) {
    videoElement.requestPictureInPicture();
  } else {
    console.log("Your browser cannot use picture-in-picture right now");
  }
}

(PiP opens if enabled; otherwise a friendly console message)

const btn = document.getElementById("pip");
btn.disabled = !document.pictureInPictureEnabled;
btn.title = document.pictureInPictureEnabled
  ? "Open picture-in-picture"
  : "Picture-in-picture is not available";

Button enabled when pictureInPictureEnabled is true

console.log("Available?", document.pictureInPictureEnabled);
console.log("Active element?", document.pictureInPictureElement);
// Available can be true while Active element is still null

Available? true
Active element? null

const supportsPiP =
  "pictureInPictureEnabled" in document &&
  document.pictureInPictureEnabled;

console.log("Safe to offer PiP?", supportsPiP);

Safe to offer PiP? true

🚀 Common Use Cases

• Guard requests — MDN pattern before requestPictureInPicture().
• Player chrome — show/hide a PiP icon based on availability.
• Feature flags — combine with "pictureInPictureEnabled" in document.
• Policy debugging — investigate Permissions-Policy blocks when the value is unexpectedly false.
• Pair with status — use pictureInPictureElement after a successful enter.
• Parallel to fullscreen — same “enabled vs active” mental model as fullscreenEnabled.

📝 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).
• PiP is available by default unless a Permissions-Policy disables it (MDN).
• This answers “can we?”; pictureInPictureElement answers “are we?”.
• Related: pictureInPictureElement, fullscreenEnabled, Document constructor.

💡 Best Practices