---
url: /guide/getting-started/overview.md
---
# Overview
Using a YouTube player in React Native usually means juggling iframe setup, event wiring, playback control, and platform differences.
`react-native-youtube-bridge` wraps the [YouTube IFrame Player API](https://developers.google.com/youtube/iframe_api_reference) in a React Native-friendly API built around three ideas:
- `useYouTubePlayer` creates and owns the player instance.
- `YoutubeView` renders the player on iOS, Android, and Web.
- `useYouTubeEvent` lets you react to player state, progress, mute, and error updates.
## Why this library exists
- No dependency on native YouTube player modules
- Cross-platform support for iOS, Android, and Web
- Hook-based API that feels natural in modern React code
- Works for both quick embeds and advanced external WebView strategies
## Core mental model
```tsx
import { YoutubeView, useYouTubePlayer } from 'react-native-youtube-bridge';
function App() {
const player = useYouTubePlayer('AbZH7XWDW_k');
return ;
}
```
The player instance is the center of the API:
- configure it when creating it
- render it through `YoutubeView`
- control it through player methods
- subscribe to updates through `useYouTubeEvent`
## Platform story
- **iOS / Android**: renders through `react-native-webview`
- **Web**: renders through the browser YouTube iframe API
- **Expo**: works well for Expo apps
- **Advanced native compatibility**: you can switch from inline HTML to an external WebView page when embed restrictions or origin constraints require it
---
url: /guide/getting-started/installation.md
---
# Installation
Install the main package:
```sh [npm]
npm install react-native-youtube-bridge
```
```sh [yarn]
yarn add react-native-youtube-bridge
```
```sh [pnpm]
pnpm add react-native-youtube-bridge
```
```sh [bun]
bun add react-native-youtube-bridge
```
```sh [deno]
deno add npm:react-native-youtube-bridge
```
## Peer dependency
`react-native-youtube-bridge` uses `react-native-webview` on iOS and Android.
Install it in your app if it is not already present:
```sh [npm]
npm install react-native-webview
```
```sh [yarn]
yarn add react-native-webview
```
```sh [pnpm]
pnpm add react-native-webview
```
```sh [bun]
bun add react-native-webview
```
```sh [deno]
deno add npm:react-native-webview
```
## Minimum expectations
| Package | Version |
| ---------------------- | ---------- |
| `react` | `>=16.8.0` |
| `react-native` | `>=0.60.0` |
| `react-native-webview` | `>=11.0.0` |
## What you get after install
The main package exports:
- `useYouTubePlayer`
- `useYouTubeEvent`
- `YoutubeView`
- public event and config types
- `useYoutubeOEmbed`
If you only need the normal player flow, you do **not** need to install `@react-native-youtube-bridge/web`.
---
url: /guide/getting-started/quick-start.md
---
# Quick Start
## Examples & Demo
- [🤖 Expo Snack](https://snack.expo.dev/@harang/react-native-youtube-bridge) - Try it instantly on Expo Snack
The smallest working example looks like this:
```tsx
import { YoutubeView, useYouTubePlayer } from 'react-native-youtube-bridge';
function App() {
const player = useYouTubePlayer('AbZH7XWDW_k');
return ;
}
```
## Accepted source forms
You can initialize the player with:
```tsx
const playerA = useYouTubePlayer('AbZH7XWDW_k');
const playerB = useYouTubePlayer({ videoId: 'AbZH7XWDW_k' });
const playerC = useYouTubePlayer({ url: 'https://www.youtube.com/watch?v=AbZH7XWDW_k' });
```
## Add initial player options
```tsx
const player = useYouTubePlayer('AbZH7XWDW_k', {
autoplay: true,
controls: true,
playsinline: true,
rel: false,
muted: true,
});
```
## Next steps
- Learn the source model in [Basic Usage](/guide/usage/basic-usage.md)
- Subscribe to updates in [Handling Events](/guide/usage/handling-events.md)
- Control playback in [Player Controls](/guide/usage/player-controls.md)
---
url: /guide/getting-started/ai.md
---
# AI
To help AI better understand this library's features, versioned documentation, and project conventions so it can provide more accurate help during development and troubleshooting, this project provides the following capabilities:
## llms.txt
[`llms.txt`](https://llmstxt.org/) helps LLMs discover and use project documentation. This site publishes the following files.
- [llms.txt](https://react-native-youtube-bridge-docs.pages.dev/llms.txt): The structured index file for the current `2.x` docs.
```txt
https://react-native-youtube-bridge-docs.pages.dev/llms.txt
```
- [llms-full.txt](https://react-native-youtube-bridge-docs.pages.dev/llms-full.txt): The full-content file that concatenates the complete `2.x` documentation into a single file.
```txt
https://react-native-youtube-bridge-docs.pages.dev/llms-full.txt
```
Choose the file that best fits your use case:
- `llms.txt` is smaller and consumes fewer tokens, so it works well when AI should fetch specific pages on demand.
- `llms-full.txt` contains the complete documentation for the current version, so AI does not need to follow individual links. This is useful for broader understanding or larger refactors, but it consumes more tokens.
## Markdown docs
Every documentation page also has a corresponding Markdown version that can be passed directly to AI.
Examples:
```txt
https://react-native-youtube-bridge-docs.pages.dev/guide/getting-started/overview.md
https://react-native-youtube-bridge-docs.pages.dev/guide/getting-started/quick-start.md
https://react-native-youtube-bridge-docs.pages.dev/guide/usage/player-controls.md
```
Providing a single Markdown page is often the most efficient option when you want help with one specific feature.
---
url: /guide/usage/basic-usage.md
---
# Basic Usage
## Create a player
```tsx
import { YoutubeView, useYouTubePlayer } from 'react-native-youtube-bridge';
function App() {
const player = useYouTubePlayer('AbZH7XWDW_k');
return ;
}
```
## Source input forms
`useYouTubePlayer` accepts:
```tsx
useYouTubePlayer('AbZH7XWDW_k');
useYouTubePlayer({ videoId: 'AbZH7XWDW_k' });
useYouTubePlayer({ url: 'https://www.youtube.com/watch?v=AbZH7XWDW_k' });
```
If the source is invalid, the player emits an error event.
## Player lifecycle
The hook owns the underlying player instance for you.
- create the player once in component scope
- pass it to `YoutubeView`
- reuse the same instance for events and controls
## Minimal configured example
```tsx
const player = useYouTubePlayer('AbZH7XWDW_k', {
autoplay: true,
controls: true,
playsinline: true,
rel: false,
});
return ;
```
---
url: /guide/usage/player-controls.md
---
# Player Controls
The player object returned by `useYouTubePlayer` exposes direct playback controls, async getters, and dynamic video loading methods.
> Async getter methods are useful after the player is ready. Before `YoutubeView` attaches the underlying controller, a getter can return `undefined`, so subscribe to `ready` before relying on these values.
## Playback actions
```tsx
player.play();
player.pause();
player.stop();
player.seekTo(30, true);
```
## Volume and mute
```tsx
player.setVolume(50);
player.mute();
player.unMute();
const volume = await player.getVolume();
const muted = await player.isMuted();
```
## Player state and video info
```tsx
const [currentTime, duration, state, loadedFraction, url, embedCode] = await Promise.all([
player.getCurrentTime(),
player.getDuration(),
player.getPlayerState(),
player.getVideoLoadedFraction(),
player.getVideoUrl(),
player.getVideoEmbedCode(),
]);
```
## Playback rate
```tsx
const currentRate = await player.getPlaybackRate();
const availableRates = await player.getAvailablePlaybackRates();
player.setPlaybackRate(1.5);
```
## Load or cue another video
```tsx
player.loadVideoById('M7lc1UVf-VE');
player.cueVideoById('M7lc1UVf-VE', 30);
```
- `loadVideoById` starts loading the target video immediately.
- `cueVideoById` prepares the target video without starting playback.
## Resize the player
```tsx
player.setSize(640, 360);
```
This is mostly useful when you need imperative size control after initial render.
## Practical toolbar example
```tsx
function Controls({ player, currentTime, isPlaying }: Props) {
return (
<>