Document Picture-in-Picture API for Custom Video Controls

The Document Picture-in-Picture API provides web developers with the ability to open an always-on-top window that can be populated with arbitrary HTML content rather than just a standalone video element. While the traditional Picture-in-Picture API restricts developers to basic browser-supplied media controls, the Document Picture-in-Picture API allows developers to maintain full control over custom video players, design systems, interactive buttons, and application state in a floating viewport.

The Limitation of Standard Video Picture-in-Picture

The legacy Picture-in-Picture API (HTMLVideoElement.requestPictureInPicture()) extracts an <video> element from the DOM and delegates playback presentation to the operating system or browser shell. This approach strips away any custom user interfaces:

  • Custom progress sliders and scrubbers are replaced with generic native timelines.
  • Custom playback controls—such as playback speed selectors, resolution switchers, and chapter menus—are completely inaccessible.
  • Interactive overlays, such as live chat, timed annotations, or synchronized subtitles, cannot be displayed alongside the media.

Because the host page cannot render DOM elements inside the standard PiP window, the user experience becomes fragmented the moment the user navigates away from the main tab.

How the Document Picture-in-Picture API Solves the Problem

The Document Picture-in-Picture API (window.documentPictureInPicture) creates a separate, lightweight browser window with its own document context while maintaining an execution context linked directly to the parent page.

Instead of isolating a video stream, the method documentPictureInPicture.requestWindow() creates a blank floating window. Developers can move both the <video> element and its surrounding custom control wrapper directly into this new document.

const pipWindow = await window.documentPictureInPicture.requestWindow({
  width: 400,
  height: 300,
});

// Move the player and its custom controls to the PiP window
const playerContainer = document.querySelector("#player-container");
pipWindow.document.body.append(playerContainer);

Direct DOM Manipulation and Shared State

A significant technical advantage of the Document Picture-in-Picture API is that it runs within the same JavaScript execution context as the originating window.

  1. Direct Event Handling: Event listeners attached to custom buttons (e.g., custom play/pause toggles, skip buttons, volume sliders) continue to function without needing an asynchronous messaging bridge like postMessage.
  2. Unified State Management: Application state, reactive frameworks (such as React, Vue, or Svelte), and media store instances remain unified. Modifying the timeline slider in the floating window immediately updates the core video player state.
  3. Seamless Window Teardown: When the floating window is closed by the user or an automated trigger, the pagehide event allows developers to cleanly re-append the video element and its controls back to the original page DOM without interrupting playback.

Preserving Styles and Visual Identity

Because the PiP window is a distinct DOM document, it does not inherit styles automatically. To maintain custom controls visually, developers must transfer style sheets or link tags into the PiP document's <head>:

[...document.styleSheets].forEach((styleSheet) => {
  try {
    const cssRules = [...styleSheet.cssRules].map((rule) => rule.cssText).join('');
    const style = document.createElement('style');
    style.textContent = cssRules;
    pipWindow.document.head.appendChild(style);
  } catch (e) {
    const link = document.createElement('link');
    link.rel = 'stylesheet';
    link.type = styleSheet.type;
    link.href = styleSheet.href;
    pipWindow.document.head.appendChild(link);
  }
});

This ensures that brand-specific themes, icon fonts, hover states, and animations display identically in both the embedded player and the floating window.

Use Cases Beyond Standard Media Players

By allowing full HTML/CSS rendering within floating windows, the API supports advanced video control paradigms:

  • Video Conferencing: Custom mute/unmute buttons, hand-raising toggles, network status indicators, and incoming chat previews remain accessible while users multi-task.
  • Interactive Streaming: Live video platforms can display pinned comments, reaction buttons, and synchronized e-commerce links directly over or beside the floating stream.
  • Complex Playlists: Users can access full playlist drawers, track navigation, and queue management inside the picture-in-picture experience.