react-styled-pip

React Document Picture-in-Picture

A React component library for creating Picture-in-Picture windows using the Document Picture-in-Picture API with styled-components support.

Browser Support

• This feature may not work in some browsers. Browser compatibility can be checked at CanIUse.

• This feature is only available in Secure Contexts (HTTPS or localhost).

Installation

npm install react-document-pip

Usage

Basic Example

import { useState } from "react";
import DocumentPip from "react-document-pip";

function App() {
  const pipWindowRef = useRef<Window | null>(null);
  const [isPipOpen, setIsPipOpen] = useState(false);

  const togglePip = () => {
    setIsPipOpen(!isPipOpen);
  };

  const handleClose = () => {
    setIsPipOpen(false);
  };

  return (
    <>
      <DocumentPip
        ref={pipWindowRef}
        isPipOpen={isPipOpen}
        size={{ width: 500, height: 400 }}
        className="dark"
        onClose={handleClose}
      >
        <MyComponent />
      </DocumentPip>
      <button onClick={togglePip}>Toggle PIP</button>
    </>
  );
}

API Reference

DocumentPIP ForwardedRef

Type	Description
Window | null	PIP window

DocumentPIP Props

Prop	Type	Default	Description
children	React.ReactNode	-	The content to display in the PIP window
isPipOpen	boolean	-	Controls whether the PIP window is open
size	Partial<PIPWindowSize>	-	Size of the PIP window
mode	'clone' | 'transfer' | 'transfer-only'	'transfer'	Content display mode clone: keep original + copy transfer: move to PIP transfer-only: move to PIP without original
copyAllStyles	boolean	true	Whether to copy all styles to PIP window
disallowReturnToOpener	boolean	false	Whether to disallow returning to the opener window
preferInitialWindowPlacement	boolean	false	Whether to prefer initial window placement
className	string	''	pip window documentElement classname
onEnter	() => void	-	Callback function when the PIP window is successfully opened
onClose	() => void	-	Callback function when the PIP window is closed

Types

interface PIPWindowSize {
  width: number;
  height: number;
}

type PIPMode = "clone" | "transfer" | "transfer-only";

interface DocumentPIPProps {
  children: React.ReactNode;
  isPipOpen: boolean;
  size?: Partial<PIPWindowSize>;
  mode?: PIPMode;
  copyAllStyles?: boolean;
  disallowReturnToOpener?: boolean;
  preferInitialWindowPlacement?: boolean;
  className?: string;

  onEnter?: (e: DocumentPictureInPictureEvent) => void;
  onClose: () => void;
}

Browser Support

This library uses the Document Picture-in-Picture API, which is currently supported in:

• Chrome 116+
• Edge 116+
• Opera 102+

License

MIT