React Native Youtube Bridge

English | 한국어

[!note] V1 users: V1 Documentation | V2 Migration Guide

Overview

Using a YouTube player in React Native requires complex setup and configuration.
However, there are currently no actively maintained YouTube player libraries for React Native. (The most popular react-native-youtube-iframe's latest release was July 2, 2023)

react-native-youtube-bridge is a library that makes it easy to use the YouTube iframe Player API in React Native applications.

• ✅ TypeScript support
• ✅ iOS, Android, and Web platform support
• ✅ New Architecture support
• ✅ Works without YouTube native player modules
• ✅ Support for various YouTube iframe Player API features
• ✅ Multiple instance support - manage multiple players independently
• ✅ Intuitive and easy-to-use Hook-based API very similar to Expo's approach
• ✅ Expo support
• ✅ Flexible rendering modes (inline HTML & webview)

Examples

If you want to get started quickly, check out the example.

• Web Demo
• Expo Go

Installation

npm install react-native-youtube-bridge

pnpm add react-native-youtube-bridge

yarn add react-native-youtube-bridge

bun add react-native-youtube-bridge

Usage

import { YoutubeView, useYouTubePlayer } from 'react-native-youtube-bridge';

function App() {
  const videoIdOrUrl = 'AbZH7XWDW_k';

  // OR useYouTubePlayer({ videoId: 'AbZH7XWDW_k' })
  // OR useYouTubePlayer({ url: 'https://youtube.com/watch?v=AbZH7XWDW_k' })
  const player = useYouTubePlayer(videoIdOrUrl);

  return <YoutubeView player={player} />;
}

Events

Events are fired to communicate YouTube iframe API state changes to your application.

The useYouTubeEvent hook provides complete type inference and allows you to easily detect and use events in two ways.

import { YoutubeView, useYouTubeEvent, useYouTubePlayer } from 'react-native-youtube-bridge';

function App() {
  const player = useYouTubePlayer(videoIdOrUrl);

  // State-based event listening
  const playbackRate = useYouTubeEvent(player, 'playbackRateChange', 1);
  const isMuted = useYouTubeEvent(player, 'muteChange', false);
  const progress = useYouTubeEvent(player, 'progress', progressInterval);

  // Callback-based event listening
  useYouTubeEvent(player, 'ready', (playerInfo) => {
    console.log('Player is ready!');
    Alert.alert('Alert', 'YouTube player is ready!');
  });

  useYouTubeEvent(player, 'autoplayBlocked', () => {
    console.log('Autoplay was blocked');
  });

  useYouTubeEvent(player, 'error', (error) => {
    console.error('Player error:', error);
    Alert.alert('Error', `Player error (${error.code}): ${error.message}`);
  });

  return <YoutubeView player={player} />;
}

muteChange emits real-time muted state updates from both the YouTube player's built-in mute control and player.mute() / player.unMute().
For performance, muted tracking is enabled only while muteChange is subscribed.

The useYouTubeEvent hook provides two ways to receive values: callback-based and state-based.

1. Callback method: If re-rendering is needed based on dependencies, inject a dependency array as the 4th argument.
2. State method:
   1. For progress events, you can set an interval value as the 3rd argument. (default: 1000ms)
   2. For other events, you can set a default value as the 3rd argument.

Features

You can control various player features like muting, playing, and volume adjustment by calling methods on the player instance returned from useYouTubePlayer, which uses the YouTube iframe API functions.

import { YoutubeView, useYouTubePlayer } from 'react-native-youtube-bridge';

function App() {
  const player = useYouTubePlayer(videoIdOrUrl);

  const [isPlaying, setIsPlaying] = useState(false);
  const [currentTime, setCurrentTime] = useState(0);

  const onPlay = useCallback(() => {
    if (isPlaying) {
      player.pause();
      return;
    }

    player.play();
  }, [isPlaying]);

  const seekTo = (time: number, allowSeekAhead: boolean) => {
    player.seekTo(time, allowSeekAhead);
  };

  const stop = () => player.stop();

  return (
    <View>
      <YoutubeView player={player} />

      <View style={styles.controls}>
        <TouchableOpacity
          style={[styles.button, styles.seekButton]}
          onPress={() => seekTo(currentTime > 10 ? currentTime - 10 : 0)}
        >
          <Text style={styles.buttonText}>⏪ -10s</Text>
        </TouchableOpacity>

        <TouchableOpacity style={[styles.button, styles.playButton]} onPress={onPlay}>
          <Text style={styles.buttonText}>{isPlaying ? '⏸️ Pause' : '▶️ Play'}</Text>
        </TouchableOpacity>

        <TouchableOpacity style={[styles.button, styles.stopButton]} onPress={stop}>
          <Text style={styles.buttonText}>⏹️ Stop</Text>
        </TouchableOpacity>

        <TouchableOpacity
          style={[styles.button, styles.seekButton]}
          onPress={() => seekTo(currentTime + 10, true)}
        >
          <Text style={styles.buttonText}>⏭️ +10s</Text>
        </TouchableOpacity>
      </View>
    </View>
  );
}

Initial Player Parameters

You can customize the initial playback environment by setting YouTube embedded player parameters.

import { YoutubeView, useYouTubePlayer } from 'react-native-youtube-bridge';

function App() {
  const player = useYouTubePlayer(videoIdOrUrl, {
    autoplay: true,
    controls: true,
    playsinline: true,
    rel: false,
    muted: true,
  });

  return <YoutubeView player={player} />;
}

Styling

You can customize the YouTube player's style as desired.

function App() {
  return (
    <YoutubeView
      player={player}
      height={400}
      width={200}
      style={{
        borderRadius: 10,
      }}
      // Web platform support
      iframeStyle={{
        aspectRatio: 16 / 9,
      }}
      // iOS, Android platform support
      webViewStyle={
        {
          // ...
        }
      }
      // iOS, Android platform support
      webViewProps={
        {
          // ...
        }
      }
    />
  );
}

Tracking Playback Progress

• You can track playback progress by registering a listener for the progress event using the useYouTubeEvent hook.
• Set an interval value as the 3rd argument to have the event called at that interval (ms).
• If you don't want an interval, set it to 0.
• The default value is 1000ms.

function App() {
  const progressInterval = 1000;

  const player = useYouTubePlayer(videoIdOrUrl);
  const progress = useYouTubeEvent(player, 'progress', progressInterval);

  return <YoutubeView player={player} />;
}

Player Rendering and Source Configuration (iOS, Android)

Inline HTML vs WebView Mode
Control the YouTube player rendering method and set source URLs for compatibility.

1. Inline HTML mode (useInlineHtml: true) renders the player by loading HTML directly within the app. (default)
2. WebView mode (useInlineHtml: false) loads an external player page.
   • The default URI is https://react-native-youtube-bridge.pages.dev.
   • To use your own custom player page as an external WebView, build your player with @react-native-youtube-bridge/web and set the URL in the webViewUrl property. For detailed implementation instructions, please refer to the Web Player Guide.

[!NOTE] webViewUrl Usage

• When useInlineHtml: true: Set as the HTML baseUrl of the WebView source.
• When useInlineHtml: false: Overrides the WebView source's uri.

Resolving Embed Restrictions: If you encounter embed not allowed errors from the YouTube iframe when using inline HTML and the video doesn't load properly, switch to WebView mode to load the YouTube iframe through an external player.

// Inline HTML (default)
<YoutubeView
  player={player}
  useInlineHtml
/>

// External WebView using custom player page
<YoutubeView
  player={player}
  useInlineHtml={false}
  // default: https://react-native-youtube-bridge.pages.dev
  webViewUrl="https://your-custom-player.com"
/>

Custom Player Page

To use a custom player page you've created, you can build a React-based player page using @react-native-youtube-bridge/web.

import { YoutubePlayer } from '@react-native-youtube-bridge/web';

function CustomPlayerPage() {
  return <YoutubePlayer />;
}

export default CustomPlayerPage;

For more details, please refer to the Web Player Guide.

YouTube oEmbed API

You can fetch YouTube video metadata through the useYoutubeOEmbed hook.
This hook only supports YouTube URLs.

import { useYoutubeOEmbed } from 'react-native-youtube-bridge';

function App() {
  const { oEmbed, isLoading, error } = useYoutubeOEmbed(
    'https://www.youtube.com/watch?v=AbZH7XWDW_k',
  );

  if (isLoading) return <Text>Loading...</Text>;
  if (error) return <Text>Error: {error.message}</Text>;
  if (!oEmbed) return null;

  return (
    <>
      <Text>{oEmbed.title}</Text>
      <Image
        source={{ uri: oEmbed?.thumbnail_url }}
        style={{ width: oEmbed?.thumbnail_width, height: oEmbed?.thumbnail_height }}
      />
    </>
  );
}

Contributing

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

License

MIT