React Native Youtube Bridge

English | 한국어

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
• ✅ YouTube iframe Player API feature support
• ✅ Developer-friendly API
• ✅ Expo support
• ✅ Flexible rendering modes (Inline HTML & WebView)

Example

For a quick start, check out the example.

• Web Demo
• Expo Go

Installation

1npm install react-native-youtube-bridge
2
3pnpm add react-native-youtube-bridge
4
5yarn add react-native-youtube-bridge
6
7bun add react-native-youtube-bridge

Usage

1import { YoutubePlayer } from 'react-native-youtube-bridge';
2
3function App() {
4  return (
5    <YoutubePlayer 
6      source={source} // youtube videoId or url
7      // OR source={{ videoId: 'AbZH7XWDW_k' }}
8      // OR source={{ url: 'https://youtube.com/watch?v=AbZH7XWDW_k' }}
9    />
10  )
11}

Events

The library fires events to notify your application of YouTube iframe API state changes. You can subscribe to these events using callback functions.

🔔 Note - Wrap callback functions with useCallback for performance optimization and to prevent abnormal behavior.

1function App() {
2  const playerRef = useRef<PlayerControls>(null);
3
4  const handleReady = useCallback(() => {
5    console.log('Player is ready!');
6  }, []);
7
8  const handleStateChange = useCallback((state: PlayerState) => {
9    console.log('Player state changed:', state);
10  }, []);
11
12  const handlePlaybackRateChange = useCallback((rate: number) => {
13    console.log('Playback rate changed:', rate);
14  }, []);
15
16  const handlePlaybackQualityChange = useCallback((quality: string) => {
17    console.log('Playback quality changed:', quality);
18  }, []);
19
20  const handleAutoplayBlocked = useCallback(() => {
21    console.log('Autoplay was blocked');
22  }, []);
23
24  const handleError = useCallback((error: YouTubeError) => {
25    console.error('Player error:', error);
26  }, []);
27
28  return (
29    <YoutubePlayer
30      onReady={handleReady}
31      onStateChange={handleStateChange}
32      onError={handleError}
33      onPlaybackRateChange={handlePlaybackRateChange}
34      onPlaybackQualityChange={handlePlaybackQualityChange}
35      onAutoplayBlocked={handleAutoplayBlocked}
36    />
37  )
38}

Functions

You can control various player features like mute, play, volume, and more by calling YouTube iframe API functions through the ref.

1function App() {
2  const playerRef = useRef<PlayerControls>(null);
3
4  const [isPlaying, setIsPlaying] = useState(false);
5  const [currentTime, setCurrentTime] = useState(0);
6
7  const onPlay = useCallback(() => {
8    if (isPlaying) {
9      playerRef.current?.pause();
10      return;
11    }
12
13    playerRef.current?.play();
14  }, [isPlaying]);
15
16  const seekTo = useCallback((time: number, allowSeekAhead: boolean) => {
17    playerRef.current?.seekTo(time, allowSeekAhead);
18  }, []);
19
20  const stop = () => playerRef.current?.stop();
21
22  return (
23    <View>
24      <YoutubePlayer
25        ref={playerRef}
26        source={source}
27      />
28
29      <View style={styles.controls}>
30        <TouchableOpacity
31          style={[styles.button, styles.seekButton]}
32          onPress={() => seekTo(currentTime > 10 ? currentTime - 10 : 0)}
33        >
34          <Text style={styles.buttonText}>⏪ -10s</Text>
35        </TouchableOpacity>
36
37        <TouchableOpacity style={[styles.button, styles.playButton]} onPress={onPlay}>
38          <Text style={styles.buttonText}>{isPlaying ? '⏸️ Pause' : '▶️ Play'}</Text>
39        </TouchableOpacity>
40
41        <TouchableOpacity style={[styles.button, styles.stopButton]} onPress={stop}>
42          <Text style={styles.buttonText}>⏹️ Stop</Text>
43        </TouchableOpacity>
44
45        <TouchableOpacity
46          style={[styles.button, styles.seekButton]}
47          onPress={() => seekTo(currentTime + 10, true)}
48        >
49          <Text style={styles.buttonText}>⏭️ +10s</Text>
50        </TouchableOpacity>
51      </View>
52    </View>
53  )
54}

Player Parameters

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

1function App() {
2  return (
3    <YoutubePlayer
4      source={source}
5      playerVars={{
6        autoplay: true,
7        controls: true,
8        playsinline: true,
9        rel: false,
10        muted: true,
11      }}
12    />
13  )
14}

Styles

You can customize the YouTube player's styling to match your application's design.

1function App() {
2  return (
3    <YoutubePlayer
4      source={source}
5      height={400}
6      width={200}
7      style={{
8        borderRadius: 10,
9      }}
10      // Web platform support
11      iframeStyle={{
12        aspectRatio: 16 / 9,
13      }}
14      // iOS, Android platform support
15      webViewStyle={{
16        // ...
17      }}
18      // iOS, Android platform support
19      webViewProps={{
20        // ...
21      }}
22    />
23  )
24}

Playback Progress Tracking

• If progressInterval is provided, the onProgress callback will be invoked at the specified interval (in milliseconds).
• If progressInterval is undefined, 0, or null, progress tracking is disabled and onProgress will not be called.

1function App() {
2  const handleProgress = useCallback((progress: ProgressData) => {
3    setCurrentTime(progress.currentTime);
4    setDuration(progress.duration);
5    setLoadedFraction(progress.loadedFraction);
6  }, []);
7
8  return (
9    <YoutubePlayer
10      source={source}
11      progressInterval={1000}
12      onProgress={handleProgress}
13    />
14  )
15}

Player Rendering & Source Configuration (ios, android)

Inline HTML vs WebView Mode
Control YouTube player rendering method and configure 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 baseUrl for WebView source HTML.
• When useInlineHtml: false: Overrides the WebView source uri.

Embed Restriction Solution: If you encounter embed not allowed errors with YouTube iframe when using inline HTML mode and videos don't load properly, switch to WebView mode to load YouTube iframe through an external player.

1// Inline HTML (default)
2<YoutubePlayer
3 source={source}
4 useInlineHtml
5/>
6
7// External WebView with custom player page
8<YoutubePlayer
9 source={source}
10 useInlineHtml={false}
11 // default: https://react-native-youtube-bridge.pages.dev
12 webViewUrl="https://your-custom-player.com"
13/>

Custom Player Page

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

1import { YoutubePlayer } from '@react-native-youtube-bridge/web';
2
3function CustomPlayerPage() {
4  return <YoutubePlayer />;
5}
6
7export default CustomPlayerPage;

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

YouTube oEmbed API

Use the useYoutubeOEmbed hook to fetch YouTube video metadata.
This hook only supports YouTube URLs.

1import { useYoutubeOEmbed } from 'react-native-youtube-bridge';
2
3function App() {
4 const { oEmbed, isLoading, error } = useYoutubeOEmbed('https://www.youtube.com/watch?v=AbZH7XWDW_k');
5
6 if (isLoading) return <Text>Loading...</Text>;
7 if (error) return <Text>Error: {error.message}</Text>;
8 if (!oEmbed) return null;
9
10 return (
11   <>
12     <Text>{oEmbed.title}</Text>
13     <Image 
14       source={{ uri: oEmbed?.thumbnail_url }} 
15       style={{ width: oEmbed?.thumbnail_width, height: oEmbed?.thumbnail_height }} 
16     />
17   </>
18 )
19}

Contributing

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

License

MIT