JavaScript Document pictureInPictureElement Property

Beginner
5 min read
Updated: Nov 2026
3 examples
Property
Decorative image with the word PICTUREINPICTUREELEMENT

Definition

Document.pictureInPictureElement is a read-only property that returns the Element currently shown in picture-in-picture mode in this document, or null if PiP is not active (MDN).

Read the notes below before you get or set this property. Prefer feature detection when support is limited.

Syntax

Use document.pictureInPictureElement. Start with this line.

JavaScript
document.pictureInPictureElement
CallWhat it does
document.pictureInPictureElementPrimary signature.

Built into the browser. Read or assign document.pictureInPictureElement — no import required.

Library declarations
JavaScript
document.pictureInPictureElement

Parameters

ParameterDescription
PiP elementOptional. Returned node (often a <video>)

Return Value

Return ValueDescription
*Element or null

JavaScript Examples

Example 1 — Read pictureInPictureElement

On a normal page with PiP off, the value is null.

JavaScript
console.log(document.pictureInPictureElement);
console.log(document.pictureInPictureElement === null);
Try It Yourself

How It Works

  1. Read the property. No arguments — just access it.
  2. Expect null when idle. PiP is off until a video requests it.
  3. Strict null check. === null means “not in PiP.”
  4. When active. You get the Element (often a <video>) instead.

Example 2 — Exit Helper (MDN Pattern)

Only call exitPictureInPicture when an element is currently in PiP.

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

exitPictureInPicture();
console.log("exit checked; active?", document.pictureInPictureElement !== null);
Try It Yourself

How It Works

  1. Truthiness check. A non-null Element means PiP is active.
  2. Call exit only then. Avoids unnecessary API calls when idle.
  3. MDN pattern. Matches the documented exitPictureInPicture helper.
  4. Re-read after. When exit succeeds, the property becomes null.

Example 3 — Feature Detect Before Using PiP

Confirm the property exists and whether PiP is enabled.

JavaScript
const hasApi = "pictureInPictureElement" in document;
const enabled = "pictureInPictureEnabled" in document
  ? document.pictureInPictureEnabled
  : false;

console.log("API present?", hasApi);
console.log("PiP enabled?", enabled);
Try It Yourself

How It Works

  1. Detect the property. Some browsers may omit the Picture-in-Picture API.
  2. Check enabled. Policy or environment can disable PiP even when the API exists.
  3. Gate UI. Hide a “Pop out” button when either check fails.
  4. Limited availability. Always feature-detect in production (MDN).
Compatibility

Browser Support

Document.pictureInPictureElement is part of the Picture-in-Picture API. MDN marks it Limited availability (not Baseline) — support varies across widely used browsers.

✓ Limited availability

Document.pictureInPictureElement

Read-only Element in PiP, or null when inactive — pair with pictureInPictureEnabled and exitPictureInPicture.

Varies Not Baseline
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Android WebView Supported · Modern WebView
Full support
pictureInPictureElement Feature-detect

Bottom line: Always feature-detect. Check pictureInPictureEnabled before requestPictureInPicture. Use pictureInPictureElement to know which element is floating and when to call exitPictureInPicture.

Frequently Asked Questions

The Element currently presented in picture-in-picture mode in this document, or null if picture-in-picture mode is not currently in use (MDN).
No. MDN marks it as Limited availability (not Baseline), but not Deprecated, Experimental, or Non-standard. Feature-detect before relying on it in production.
When PiP is not active, when there is no associated PiP element, or when the element is from an iframe (MDN).
No meaningful assignment. The property is read-only; modifying it does not throw even in strict mode — the setter is a no-operation and is ignored (MDN).
MDN: if document.pictureInPictureElement is truthy, call document.exitPictureInPicture(). Users can also close PiP with browser UI.
fullscreenElement returns the element in fullscreen mode. pictureInPictureElement returns the element in the floating PiP window. They are separate APIs.

Next: pictureInPictureEnabled

Learn how to check whether Picture-in-Picture is available before requesting it.

pictureInPictureEnabled tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

10 people found this page helpful

JavaScript Document location Property JavaScript Document pictureInPictureEnabled Property