@jaydhimar/react-native-pip

A React Native library for Picture-in-Picture (PiP) mode support on iOS and Android. This library provides a simple interface to implement PiP functionality in your React Native applications.

Features

✅ Custom Aspect Ratio Selection ✅ Auto-PiP on Home Button Press ✅ Detect if PiP is Supported ✅ Callbacks for PiP Events

Requirements

iOS 14.0 or later
Android API level 26 (Android 8.0) or later
React Native 0.63 or later

Installation

npm install @jaydhimar/react-native-pip
# or
yarn add @jaydhimar/react-native-pip

Android Setup

Add the following to your AndroidManifest.xml inside the <activity> tag that hosts your React Native content:

android:supportsPictureInPicture="true"
android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|screenLayout|uiMode"

iOS Setup

Add the following to your Info.plist:

<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

Usage

import PictureInPicture from 'react-native-pip';

// Check if PiP is supported on the device
const isPipSupported = await PictureInPicture.isPipSupported();

// Enter PiP mode with custom aspect ratio
await PictureInPicture.enterPictureInPicture({
  aspectRatio: {
    width: 16,
    height: 9
  },
  autoEnterOnBackground: true // iOS only
});

// Exit PiP mode
await PictureInPicture.exitPictureInPicture();

// Listen to PiP events
const unsubscribeEnter = PictureInPicture.addEventListener('onEnterPip', () => {
  console.log('Entered PiP mode');
});

const unsubscribeExit = PictureInPicture.addEventListener('onExitPip', () => {
  console.log('Exited PiP mode');
});

const unsubscribeError = PictureInPicture.addEventListener('onError', (error) => {
  console.error('PiP error:', error);
});

// Clean up event listeners
unsubscribeEnter();
unsubscribeExit();
unsubscribeError();

API Reference

Methods

`isPipSupported(): Promise<boolean>`

Checks if PiP mode is supported on the current device.

`enterPictureInPicture(config?: PipConfig): Promise<boolean>`

Enters PiP mode with optional configuration.

`exitPictureInPicture(): Promise<boolean>`

Exits PiP mode.

`addEventListener(eventType: string, listener: Function): () => void`

Adds an event listener for PiP events. Returns a function to remove the listener.

Types

interface PipConfig {
  aspectRatio?: {
    width: number;
    height: number;
  };
  autoEnterOnBackground?: boolean; // iOS only
}

type PipEvents = {
  onEnterPip?: () => void;
  onExitPip?: () => void;
  onError?: (error: string) => void;
}

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

Made with create-react-native-library

Package detail