Document Picture-in-Picture API: A Complete Guide

How the Document Picture-in-Picture API Works

Accessing the API

The Document Picture-in-Picture API is accessed through the window.documentPictureInPicture property, which returns a DocumentPictureInPicture object that serves as the entry point for creating and managing Picture-in-Picture windows MDN Web Docs. This object provides the essential methods and properties needed to work with Picture-in-Picture functionality.

Before attempting to use the API, applications should check for browser support to implement appropriate fallback behavior. This can be accomplished by testing for the presence of the documentPictureInPicture property on the window object. If the property is not present, the browser does not support the API, and the application should either disable related functionality or provide alternative user experiences.

Creating a Picture-in-Picture Window

The primary method for creating a Picture-in-Picture window is the requestWindow() method, which is called on the DocumentPictureInPicture instance MDN Web Docs. This method accepts an optional configuration object that can specify the desired dimensions of the window using width and height properties. When called, the method returns a Promise that resolves with a reference to the new window's Window object once the Picture-in-Picture window has been successfully created.

The following code demonstrates the basic pattern for creating a Picture-in-Picture window:

// Check for API support
if ("documentPictureInPicture" in window) {
 // Request a Picture-in-Picture window with specific dimensions
 const pipWindow = await window.documentPictureInPicture.requestWindow({
 width: 400,
 height: 600
 });
}

The dimensions specified in the request are considered hints rather than absolute requirements. Browsers may adjust the actual dimensions based on security considerations, user preferences, or platform constraints Telerik Developer Blog. Applications should design their content to be responsive and adapt gracefully to whatever dimensions the browser provides.

Working with the Picture-in-Picture Window

Once the Promise returned by requestWindow() resolves, developers receive a reference to the Picture-in-Picture window's Window object MDN Web Docs. This reference enables manipulation of the window's document, including adding content to the body, applying styles, and registering event listeners for window lifecycle events.

Content can be added to the Picture-in-Picture window using standard DOM manipulation methods. Elements from the parent window can be moved into the Picture-in-Picture window using methods like append(), which moves the actual DOM nodes rather than creating copies Telerik Developer Blog. This approach preserves the state of elements, such as video playback position, form input values, or interactive component states, allowing for seamless transitions between the main window and the Picture-in-Picture window.

// Move elements to the Picture-in-Picture window
pipWindow.document.body.append(playerContainer);
pipWindow.document.body.append(customControls);

// Apply custom styling
pipWindow.document.body.style.backgroundColor = "#1a1a2e";

Styling can be applied to the Picture-in-Picture window's document using the same CSS properties and approaches used for regular web pages. Developers can set styles directly on elements, apply CSS classes, or even copy entire stylesheets from the parent window to ensure visual consistency.

Handling Window Closure

The Picture-in-Picture window can be closed through user interaction with the browser's native close control, or programmatically through the close() method called on the Picture-in-Picture window's Window object Telerik Developer Blog. Regardless of how the window is closed, the pagehide event fires on the Picture-in-Picture window, allowing applications to perform cleanup operations and restore content to the parent window.

This event-driven approach enables seamless restoration of the user experience:

pipWindow.addEventListener("pagehide", () => {
 // Move elements back to the parent window
 const elements = pipWindow.document.body.children;
 document.body.append(...elements);

 // Update UI state
 openPipButton.style.display = "inline-block";
 closePipButton.style.display = "none";
});

Applications should implement this event handler to ensure that content moved to the Picture-in-Picture window is properly restored when the window closes, maintaining application state and preventing content loss. This pattern is essential for building robust JavaScript applications that use the Document PiP API.

Browser Support and Progressive Enhancement

Current Browser Compatibility

The Document Picture-in-Picture API is a relatively new feature with limited but growing browser support Chrome for Developers. As of the latest available information, the API is supported in Chrome version 116 and later, as well as in Edge version 116 and later, which share the same underlying Chromium engine. Firefox and Safari do not yet support this API, representing a significant portion of the browser market where the functionality will not be available.

This limited availability means that applications implementing the Document Picture-in-Picture API must do so with careful consideration for users on unsupported browsers. The recommended approach is to treat Picture-in-Picture functionality as an enhancement rather than a core feature, implementing appropriate fallback behavior for browsers that do not support the API Chrome for Developers.

Implementing Progressive Enhancement

Progressive enhancement is the practice of building web experiences that provide basic functionality to all users while offering enhanced experiences to users with more capable browsers Chrome for Developers. For the Document Picture-in-Picture API, this means designing applications so that core functionality works without Picture-in-Picture, while users on supporting browsers can benefit from the additional floating window capability.

The implementation pattern begins with feature detection:

const isPipSupported = "documentPictureInPicture" in window;

// If supported, enable the Picture-in-Picture feature
if (isPipSupported) {
 pipButton.addEventListener("click", openPictureInPicture);
 pipButton.textContent = "Open Picture-in-Picture";
} else {
 // Disable or hide the button for unsupported browsers
 pipButton.disabled = true;
 pipButton.textContent = "Picture-in-Picture not supported";
}

This approach ensures that users on unsupported browsers are not presented with broken functionality. Instead, they can continue using the application normally, while users with supporting browsers gain access to the enhanced Picture-in-Picture experience. When building modern web applications, this pattern should be standard practice for any emerging browser API.

Graceful Degradation Strategies

For applications where Picture-in-Picture represents a significant enhancement, additional strategies can be employed to maintain the user experience across all browsers. One approach involves providing alternative UI patterns for users on unsupported browsers, such as opening content in a new tab or using a split-view layout Chrome for Developers.

The choice of strategy depends on the specific application and its use case. For video-focused applications, the original video-only Picture-in-Picture API might provide a fallback option for browsers that support it. For more complex custom interfaces, new tab navigation or modal dialogs might serve as reasonable alternatives that provide similar utility. The key is ensuring that users on any browser can accomplish their core tasks effectively.

Applications should also consider providing visual indicators that highlight the availability of Picture-in-Picture features for users who can benefit, while keeping the interface functional for everyone. This balanced approach maximizes the value of the API while maintaining broad accessibility.

Practical Implementation Guide

Building a Custom Video Player

One compelling use case for the Document Picture-in-Picture API is creating custom video players that can be detached into a floating window while users continue working in other applications MDN Web Docs. Unlike the traditional video-only Picture-in-Picture, this approach allows developers to include custom controls, playback statistics, chapter navigation, or additional content alongside the video.

The implementation involves creating a complete player interface in HTML, including the video element and any custom controls, then moving this entire container into the Picture-in-Picture window when activated:

const playerContainer = document.getElementById("player");
const videoElement = document.getElementById("video");
const customControls = document.getElementById("controls");

async function openPictureInPicture() {
 const pipWindow = await window.documentPictureInPicture.requestWindow({
 width: 500,
 height: 400
 });

 // Move entire player interface to Picture-in-Picture window
 pipWindow.document.body.append(playerContainer);
 pipWindow.document.body.append(customControls);

 // Apply consistent styling
 copyStyles(pipWindow.document);
}

This approach preserves all functionality in the floating window, including custom JavaScript-based controls, interactive elements, and any dynamic behavior implemented in the player interface. For video streaming platforms and e-learning applications, this capability significantly enhances the user experience.

Styling Consistency Across Windows

Maintaining visual consistency between the main window and the Picture-in-Picture window enhances the user experience and reinforces the connection between the two contexts Telerik Developer Blog. Several approaches can achieve this consistency.

The most straightforward method is to copy stylesheets from the parent document to the Picture-in-Picture document:

function copyStyles(sourceDoc) {
 const stylesheets = Array.from(document.styleSheets);

 stylesheets.forEach(stylesheet => {
 try {
 const rules = stylesheet.cssRules;
 if (rules) {
 const styleSheet = sourceDoc.createElement("style");
 styleSheet.textContent = Array.from(rules)
 .map(rule => rule.cssText)
 .join("\n");
 sourceDoc.head.appendChild(styleSheet);
 }
 } catch (e) {
 // Cross-origin stylesheets cannot be accessed
 }
 });
}

This approach ensures that CSS custom properties, component styles, and global design tokens are available in the Picture-in-Picture window, creating a seamless visual experience that aligns with your application's design system.

Managing State Across Window Transitions

When moving elements between the main window and the Picture-in-Picture window, careful state management ensures that the user experience remains consistent Telerik Developer Blog. Using append() rather than cloning preserves element state, but developers should be aware of edge cases that might cause state loss.

For complex applications, implementing explicit state synchronization provides additional robustness:

function saveElementState(element) {
 return {
 scrollPosition: element.scrollTop,
 formValues: captureFormValues(element),
 activeElement: element.contains(document.activeElement)
 ? document.activeElement.id : null
 };
}

function restoreElementState(element, state) {
 if (state.scrollPosition) {
 element.scrollTop = state.scrollPosition;
 }
 restoreFormValues(element, state.formValues);
 if (state.activeElement) {
 const el = document.getElementById(state.activeElement);
 if (el) el.focus();
 }
}

This pattern is particularly important for single-page applications where maintaining state across different views and contexts is critical to the user experience.

Best Practices for Implementation

Content Design

When designing content for Picture-in-Picture windows, developers should consider the unique constraints and opportunities of the floating window context Chrome for Developers. The window is typically smaller than the main browser window, so content should be designed to work well at reduced sizes. Responsive design principles become especially important, as the actual dimensions of the Picture-in-Picture window may vary based on browser implementation and user preferences.

Key considerations for content design include:

• Responsive layouts - Content should adapt to varying window dimensions, using flexible units and CSS Grid or Flexbox
• Reduced complexity - Simplify layouts for smaller, always-visible windows, focusing on essential information
• At-a-glance information - Focus on content that provides ongoing value without requiring sustained attention

Performance Optimization

Picture-in-Picture windows share the same process model as the parent document, which has implications for performance management MDN Web Docs. Developers should be mindful of resource consumption, particularly for features like video playback or real-time data updates that may continue running in the Picture-in-Picture window while the user is focused on other content.

Effective performance strategies include:

• Pausing resource-intensive operations when the Picture-in-Picture window loses focus
• Implementing efficient update cycles for real-time data using requestAnimationFrame or similar techniques
• Minimizing layout complexity in the Picture-in-Picture window to reduce rendering overhead

These optimizations help ensure that the Picture-in-Picture feature enhances rather than detracts from overall application performance, which is essential for high-performance web applications.

User Experience Guidelines

Successful implementations of Picture-in-Picture functionality prioritize clear user control and expectations. Users should understand when Picture-in-Picture mode is active and have easy access to controls for managing the floating window Chrome for Developers. Transitions between the main window and Picture-in-Picture should feel natural, with content state preserved across the transition.

Visual design should maintain consistency between the Picture-in-Picture window and the main application, helping users recognize that the floating window is part of the same application experience. This can be achieved through consistent use of colors, typography, and design patterns, as well as through explicit branding within the Picture-in-Picture interface.

Security Considerations

The Picture-in-Picture API includes security mechanisms to prevent abuse MDN Web Docs. Window dimensions are constrained to prevent creating windows that might be used for phishing or other malicious purposes. The floating window cannot be navigated to arbitrary URLs, preventing it from being used to display untrusted content. The Picture-in-Picture window automatically closes when the parent document is closed, preventing orphaned windows.

Developers should work within these security constraints rather than attempting to circumvent them. The constraints exist to protect users, and designs that work within these boundaries will provide better, safer user experiences. When building secure web applications, understanding these built-in protections is essential for leveraging the API effectively.

Sources

1. MDN Web Docs - Document Picture-in-Picture API - Official API reference with technical specifications, interface definitions, and browser support matrix.
2. Chrome for Developers - Unlock exciting use cases with the Document Picture-in-Picture API - Google's official documentation on use cases, progressive enhancement strategies, and implementation guidance.
3. W3C Picture-in-Picture Specification - The official W3C specification for Picture-in-Picture APIs.
4. MDN Web Docs - Picture-in-Picture API - Reference for the original video-only PiP API that Document PiP extends.
5. Telerik - Getting Started with the Document Picture-in-Picture API - A practical tutorial guide with complete code examples showing how to build applications with video and image elements.