Unlock exciting use cases with the Document Picture-in-Picture API

Jad Joubran

Published: March 4, 2025

The Document Picture-in-Picture API (Document PiP API) lets web applications open a floating, always-on-top window (a picture-in-picture window) that can display any arbitrary HTML content.

This API builds on top of the Picture-in-Picture API for <video>, which lets you continue consuming video in a PiP window.

As the Document PiP API can display any arbitrary HTML content, you can use it to unlock exciting new use cases.

Browser support and progressive enhancement

Browser Support

Source

At the time of writing, the Document Picture-in-Picture API has limited availability.

However, this shouldn't stop you from using it with progressive enhancement or graceful degradation.

When planning your use case, make sure to treat it as a progressive enhancement rather than a standard feature. In this article, you'll see an example of graceful degradation.

Improving the learner's user experience with the Document PiP API

LearnHTMLCSS.online is an interactive learning platform that teaches semantic and accessible HTML and CSS. It offers an interactive text editor and browser preview window.

The following screencast shows the layout of the app; the screen is divided into two columns. The first column contains the code editor. The second column contains a tabbed layout. By default, the user can see the instructions of the challenge, and they can click the Browser tab to view a live preview.

As a student, you might sometimes want to maximise the browser preview window. This is a perfect opportunity to add support for the Document Picture-in-Picture API.

To implement this, start by checking for browser support:

const isPipSupported = "documentPictureInPicture" in window;

You can now use this variable to wrap any documentPictureInPicture calls, or to early return from a function that relies on Document PiP. The following code checks for support of Document PiP, then opens a Document PiP window.

async function initDocumentPip() {
  if (!isPipSupported) {
    return false;
  }

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

Depending on your use case, you can specify any width and height for the window. You can try to match a particular element, the current document, or even provide fixed values.

So far, you have an empty document. You now need to populate it with content.

// htmlCode is the HTML code of the challenge
pipWindow.document.documentElement.innerHTML = htmlCode;

For challenges with CSS code, you will also need to sync the CSS.

That's it! You now have a maximize button that opens in a separate PiP window.In addition to maximizing the browser preview tab, you can also move it to a separate screen if you have an external monitor, or even rearrange the main web app and the browser preview tab in a column layout.

Fallback

Remember that this API has limited availability. On browsers and devices where this API is not supported, you'll need to provide a fallback (graceful degradation) behavior.

Instead of making the maximize button pull the whole browser preview tab out, we can make it take up all the remaining space of the current web app.

Try this behavior in different browsers: https://learnhtmlcss.online/app.html?id=2096

Don't forget to pay attention to small details in the tooltips. When isPipSupported is true, the maximize/minimize button's tooltip toggles between Enter Picture-in-Picture and Exit Picture-in-Picture. On the other hand, when isPipSupported is false, the fallback behavior is described with Maximize and Minimize.

As you can see, the Document Picture-in-Picture API can unlock exciting new use cases for your Web App when combined with progressive enhancement or graceful degradation.

Don't let limited browser support limit you, and don't forget to have a decent fallback use case.

Check out the documentation for Document PiP to explore various examples and use cases of this API.