React Document Picture-in-Picture

A React component library for creating Picture-in-Picture windows using the Document Picture-in-Picture API.

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 [isPipOpen, setIsPipOpen] = useState(false);

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

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

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

Using Window Methods Or Web APIs in PIP window

// ...

const pipWindowRef = useRef<Window | null>(null);

const onClickButton = () => {
  pipWindowRef.current?.alert("alert in pip window");
};

function App() {
  return (
    <>
      <DocumentPip
        mode="transfer-only"
        ref={pipWindowRef}
        isPipOpen={isPipOpen}
        onClose={handleClose}
      >
        <div className="pip-content">
          <h1>PIPContent</h1>
          <button onClick={onClickButton}>BUTTON</button>
        </div>
      </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 modeclone: keep original + copytransfer: move to PIPtransfer-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 opesuccessfully 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+

Styled Components not supported

Related Packages

• vue-pip - Vue version of Document Picture-in-Picture

License

MIT