react-native-youtube react-native-youtube npm version Dependency Status

A <YouTube /> component for React Native.

Uses YoutubePlayer-in-WKWebView for iOS and YouTube Android Player API for Android and exposes much of the API, as declaratively as possible, into React Native.

Having problems with Android? Please read this first

Important!!! - This README is for v2. Latest README for v1 can be found here

Table of Contents


Screenshot of the example app


Install the latest version to your package.json:

$ npm install react-native-youtube -S

React Native automatically connects this native module to your iOS and Android projects. On Android this linking is supported with Gradle and is done automatically after installation. On iOS the linking is done by Cocoapods, without the need to add this library to the Podfile, Just run pod install after installation.

IMPORTANT! (Android Only): The Android implementation of this component needs to have the official YouTube app installed on the device. Otherwise the user will be prompted to install / activate the app, and an error event will be triggered with SERVICE_MISSING/SERVICE_DISABLED.

OPTIONAL: Activated sound when iPhone (iOS) is on vibrate mode

Open AppDelegate.m and add :


  videoId="KVZ-P-ZI6W4" // The YouTube video ID
  play // control playback of video with true/false
  fullscreen // control whether the video should play in fullscreen or inline
  loop // control whether the video should loop when ended
  onReady={e => this.setState({ isReady: true })}
  onChangeState={e => this.setState({ status: e.state })}
  onChangeQuality={e => this.setState({ quality: e.quality })}
  onError={e => this.setState({ error: e.error })}
  style={{ alignSelf: 'stretch', height: 300 }}


YouTube Component


import YouTube from 'react-native-youtube';


The iOS implementation of this player uses the official YouTube iFrame under the hood, so most parameters behavior can be further understood here.



Standalone Player (iOS)


Standalone iOS player Uses XCDYoutubeKit (Warning: XCDYoutubeKit doesn't conform to YouTube's Terms Of Use). Add the next line to your Podfile and run pod install inside /ios folder:

pod 'XCDYouTubeKit', '~> 2.8'


import { YouTubeStandaloneIOS } from 'react-native-youtube';


  .then(message => console.log(message))
  .catch(errorMessage => console.error(errorMessage));

YouTubeStandaloneIOS.playVideo(videoId) (Static)

A static method that returns a Promise to launch a standalone YouTube player with a specific video.

Standalone Player (Android)


import { YouTubeStandaloneAndroid } from 'react-native-youtube';


  apiKey: 'YOUR_API_KEY', // Your YouTube Developer API Key
  videoId: 'KVZ-P-ZI6W4', // YouTube video ID
  autoplay: true, // Autoplay the video
  startTime: 120, // Starting point of video (in seconds)
  .then(() => console.log('Standalone Player Exited'))
  .catch(errorMessage => console.error(errorMessage));

YouTubeStandaloneAndroid.playVideo(options) (Static)

A static method that returns a Promise to launch a standalone YouTube player with a specific video.

options is an object with properties:

YouTubeStandaloneAndroid.playVideos(options) (Static)

A static method that returns a Promise to launch a standalone YouTube player with a specific video.

options is an object with properties:

YouTubeStandaloneAndroid.playPlaylist(options) (Static)

A static method that returns a Promise to launch a standalone YouTube player with a specific video.

options is an object with properties:

Known Issues


The Android version of this component is based on the official Java YouTube Android Player API which limits the ability to cover player view, or render it too small. Some React Native components such as navigation ones can interfere with these limitations in unpredictable ways. This issue is discussed in #161.

Changing videoId / videoIds / playlistId while the component is mounted in Android

The Android API has bugs when props that identify the videos are changed during the lifecycle of the native component. For now it is recommended to re-mount a new <YouTube /> instance each time there is a need to replace the video or playlist of a player. Also, looping through a playlist or videoIds is broken due to the underlying library's bugs.

Multiple <YouTube /> instances on Android

The YouTube API for Android is a singleton. What it means is that unlike the iOS implementation, no two players can be mounted and play a video at the same time. If you have two scenes that happen to live together, or come one after the other (such as when navigating to a new scene), The new <YouTube /> Will take the focus of the singleton and play the video, but after being unmounted, the older mounted <YouTube /> will not be able to take the role back, and will need to be re-mounted.

Example App and Development

This repository includes an example project that can be used for trying, developing and testing all functionalities on a dedicated clean app project.

First, copy the git repository and install the React-Native project inside /example:

$ git clone
$ cd react-native-youtube/example
$ npm install

For iOS, also install the Cocoapods

$ cd ios
$ pod install

Then build and run with react-native run-ios / react-native run-android or your preferred IDE.

For Developers

To be able to directly test your changes with the example app, re-install the package from the root directory with npm run install-root after each change. This command packs the root directory into an npm package .tar file and installs it locally to the example app.



MIT License