---
url: /1.x/guide/getting-started/overview.md
---

# 1.x Overview

![Demo of react-native-youtube-bridge](https://raw.githubusercontent.com/react-native-bridges/react-native-youtube-bridge/main/assets/example.gif)
Version 1.x is the legacy component-based API for `react-native-youtube-bridge`.

It wraps the [YouTube IFrame Player API](https://developers.google.com/youtube/iframe_api_reference) for React Native apps and uses a single `YoutubePlayer` component with callback props and an imperative ref.

## Key features

- TypeScript support
- iOS, Android, and Web support
- New Architecture support
- No native YouTube player module dependency
- YouTube IFrame Player API feature support
- Expo-friendly setup
- Inline HTML and external WebView rendering modes

Use this version lane when maintaining an existing 1.x integration. For new work, prefer the 2.x hook-based docs.



---
url: /1.x/guide/getting-started/installation.md
---

# Installation

:::warning Legacy version
Version 1.x is the legacy API. New projects should install the latest 2.x version unless they specifically need to maintain an existing 1.x integration.
:::

Install the 1.x package:


```sh [npm]
npm install react-native-youtube-bridge@1.x
```

```sh [yarn]
yarn add react-native-youtube-bridge@1.x
```

```sh [pnpm]
pnpm add react-native-youtube-bridge@1.x
```

```sh [bun]
bun add react-native-youtube-bridge@1.x
```

```sh [deno]
deno add npm:react-native-youtube-bridge@1.x
```

## Peer dependency

`react-native-youtube-bridge` uses `react-native-webview` on iOS and Android.


```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` |



---
url: /1.x/guide/getting-started/quick-start.md
---

# Quick Start

## Install


```sh [npm]
npm install react-native-youtube-bridge@1.x
```

```sh [yarn]
yarn add react-native-youtube-bridge@1.x
```

```sh [pnpm]
pnpm add react-native-youtube-bridge@1.x
```

```sh [bun]
bun add react-native-youtube-bridge@1.x
```

```sh [deno]
deno add npm:react-native-youtube-bridge@1.x
```

## Basic player

```tsx
import { YoutubePlayer } from 'react-native-youtube-bridge';

function App() {
  return <YoutubePlayer source="AbZH7XWDW_k" />;
}
```

## Accepted source forms

```tsx
<YoutubePlayer source="AbZH7XWDW_k" />
<YoutubePlayer source={{ videoId: 'AbZH7XWDW_k' }} />
<YoutubePlayer source={{ url: 'https://youtube.com/watch?v=AbZH7XWDW_k' }} />
```

## Next steps

- Learn the component API in [Basic Usage](/1.x/guide/usage/basic-usage.md)
- Control the player in [Player Controls](/1.x/guide/usage/player-controls.md)
- Move to 2.x with the [Migration Guide](/1.x/guide/migration-from-1.x.md)



---
url: /1.x/guide/getting-started/ai.md
---

# AI

To help AI better understand this library's `1.x` behavior, 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. For `1.x`, use the following files.

- [1.x/llms.txt](https://react-native-youtube-bridge-docs.pages.dev/1.x/llms.txt): The structured index file for the `1.x` docs.

```txt
https://react-native-youtube-bridge-docs.pages.dev/1.x/llms.txt
```

- [1.x/llms-full.txt](https://react-native-youtube-bridge-docs.pages.dev/1.x/llms-full.txt): The full-content file that concatenates the complete `1.x` documentation into a single file.

```txt
https://react-native-youtube-bridge-docs.pages.dev/1.x/llms-full.txt
```

## 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/1.x/guide/getting-started/overview.md
https://react-native-youtube-bridge-docs.pages.dev/1.x/guide/getting-started/quick-start.md
https://react-native-youtube-bridge-docs.pages.dev/1.x/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: /1.x/guide/usage/basic-usage.md
---

# Basic Usage

Version 1.x centers on the `YoutubePlayer` component.

```tsx
import { YoutubePlayer } from 'react-native-youtube-bridge';

function App() {
  return <YoutubePlayer source="AbZH7XWDW_k" height={240} width="100%" />;
}
```

## Source input

`source` can be a video ID, a `{ videoId }` object, or a `{ url }` object.

```tsx
<YoutubePlayer source="AbZH7XWDW_k" />
<YoutubePlayer source={{ videoId: 'AbZH7XWDW_k' }} />
<YoutubePlayer source={{ url: 'https://youtube.com/watch?v=AbZH7XWDW_k' }} />
```



---
url: /1.x/guide/usage/player-controls.md
---

# Player Controls

Version 1.x exposes player controls through a `ref`.

```tsx
import { useRef } from 'react';
import { Button, View } from 'react-native';
import { YoutubePlayer, type PlayerControls } from 'react-native-youtube-bridge';

function App() {
  const playerRef = useRef<PlayerControls>(null);

  return (
    <View>
      <YoutubePlayer ref={playerRef} source="AbZH7XWDW_k" />
      <Button title="Play" onPress={() => playerRef.current?.play()} />
      <Button title="Pause" onPress={() => playerRef.current?.pause()} />
      <Button title="Seek" onPress={() => playerRef.current?.seekTo(30, true)} />
    </View>
  );
}
```

## Common methods

- `play`, `pause`, `stop`, `seekTo`
- `setVolume`, `getVolume`, `mute`, `unMute`, `isMuted`
- `getCurrentTime`, `getDuration`, `getVideoUrl`, `getVideoEmbedCode`
- `getPlaybackRate`, `setPlaybackRate`, `getAvailablePlaybackRates`
- `getPlayerState`, `getVideoLoadedFraction`
- `loadVideoById`, `cueVideoById`, `setSize`



---
url: /1.x/guide/usage/handling-events.md
---

# Handling Events

In 1.x, player events are callback props on `YoutubePlayer`.

> Wrap callbacks with `useCallback` for stable references and better performance.

```tsx
import { useCallback } from 'react';
import { YoutubePlayer, PlayerState } from 'react-native-youtube-bridge';

function App() {
  const handleReady = useCallback(() => {
    console.log('Player is ready');
  }, []);

  const handleStateChange = useCallback((state: PlayerState) => {
    console.log('state', state);
  }, []);

  return (
    <YoutubePlayer
      source="AbZH7XWDW_k"
      onReady={handleReady}
      onStateChange={handleStateChange}
      onError={(error) => console.error(error)}
      onPlaybackRateChange={(rate) => console.log('rate', rate)}
      onPlaybackQualityChange={(quality) => console.log('quality', quality)}
      onAutoplayBlocked={() => console.log('autoplay blocked')}
    />
  );
}
```

## Progress

Use `progressInterval` with `onProgress` to receive playback progress.

```tsx
<YoutubePlayer
  source="AbZH7XWDW_k"
  progressInterval={1000}
  onProgress={(progress) => {
    console.log(progress.currentTime, progress.duration, progress.loadedFraction);
  }}
/>
```



---
url: /1.x/guide/usage/player-config.md
---

# Player Config

Use `playerVars` to configure the initial YouTube playback environment.

```tsx
<YoutubePlayer
  source="AbZH7XWDW_k"
  playerVars={{
    autoplay: true,
    controls: true,
    playsinline: true,
    rel: false,
    muted: true,
  }}
/>
```

Common options include `autoplay`, `controls`, `loop`, `muted`, `startTime`, `endTime`, `playsinline`, `rel`, and `origin`.



---
url: /1.x/guide/usage/styling-and-layout.md
---

# Styling and Layout

`YoutubePlayer` accepts sizing and platform-specific styling props.

```tsx
<YoutubePlayer
  source="AbZH7XWDW_k"
  height={400}
  width="100%"
  style={{ borderRadius: 10 }}
  iframeStyle={{ aspectRatio: 16 / 9 }}
  webViewStyle={{ backgroundColor: 'transparent' }}
/>
```

- `iframeStyle`: Web only
- `webViewStyle`: iOS / Android only
- `webViewProps`: iOS / Android only



---
url: /1.x/guide/usage/inline-html-vs-webview.md
---

# Inline HTML vs WebView

On iOS and Android, 1.x supports two render strategies.

## Inline HTML mode

```tsx
<YoutubePlayer source="AbZH7XWDW_k" useInlineHtml />
```

- default mode
- loads HTML directly inside the app

## External WebView mode

```tsx
<YoutubePlayer
  source="AbZH7XWDW_k"
  useInlineHtml={false}
  webViewUrl="https://your-custom-player.com"
/>
```

- loads an external player page
- default hosted player page: `https://react-native-youtube-bridge.pages.dev`
- useful when inline HTML runs into embed restrictions or origin constraints



---
url: /1.x/guide/usage/custom-webview-player.md
---

# Custom WebView Player

Use `@react-native-youtube-bridge/web` when you need to host your own external player page.

```bash
npm install @react-native-youtube-bridge/web
```

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

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

export default CustomPlayerPage;
```

Then pass the hosted URL from the native app:

```tsx
<YoutubePlayer
  source="AbZH7XWDW_k"
  useInlineHtml={false}
  webViewUrl="https://your-custom-player.com"
/>
```



---
url: /1.x/guide/usage/metadata-with-oembed.md
---

# Metadata with oEmbed

`useYoutubeOEmbed` fetches optional YouTube metadata for richer UI.

```tsx
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 null;
  if (error) return null;

  return <Text>{oEmbed?.title}</Text>;
}
```



---
url: /1.x/guide/usage/errors-and-troubleshooting.md
---

# Errors and Troubleshooting

This page exists so switching from the 2.x troubleshooting page to the 1.x docs does not land on a 404.

## Embed not allowed or blank player

If a video does not load in inline HTML mode, try WebView mode with the hosted player page.

```tsx
<YoutubePlayer
  source="AbZH7XWDW_k"
  useInlineHtml={false}
  webViewUrl="https://react-native-youtube-bridge.pages.dev"
/>
```

## Event callbacks behave unexpectedly

Wrap event callbacks with `useCallback` so the player does not receive unstable callback references every render.

```tsx
const handleReady = useCallback(() => {
  console.log('Player is ready');
}, []);

<YoutubePlayer source="AbZH7XWDW_k" onReady={handleReady} />;
```

## Progress does not update

Progress tracking is disabled unless `progressInterval` is provided with a positive interval.

```tsx
<YoutubePlayer source="AbZH7XWDW_k" progressInterval={1000} onProgress={handleProgress} />
```

## Prefer 2.x for new fixes

1.x is a legacy API. If you are starting a new integration or can migrate safely, use the [2.x troubleshooting guide](/1.x/guide/usage/errors-and-troubleshooting.md) and the [migration guide](/1.x/guide/migration-from-1.x.md).



---
url: /1.x/guide/usage/api-reference.md
---

# API Reference

This page summarizes the legacy 1.x component API and prevents version switching from the 2.x API reference from landing on a 404.

## Main exports

```ts
import { YoutubePlayer, useYoutubeOEmbed } from 'react-native-youtube-bridge';
import type {
  PlayerControls,
  PlayerState,
  ProgressData,
  YouTubeError,
} from 'react-native-youtube-bridge';
```

## Main component

### `YoutubePlayer`

Renders a YouTube player directly and exposes imperative controls through `ref`.

```tsx
const playerRef = useRef<PlayerControls>(null);

<YoutubePlayer ref={playerRef} source="AbZH7XWDW_k" />;
```

## Common props

- `source`: YouTube video ID, YouTube URL, or source object.
- `playerVars`: YouTube embedded player parameters.
- `height` / `width`: player size.
- `style`: React Native player container style.
- `iframeStyle`: iframe wrapper style on web.
- `webViewStyle`: WebView style on iOS and Android.
- `webViewProps`: additional WebView props on iOS and Android.
- `useInlineHtml`: choose inline HTML or external WebView mode on iOS and Android.
- `webViewUrl`: custom WebView source URL or inline HTML `baseUrl`.
- `progressInterval`: enables `onProgress` when set to a positive interval.

## Event props

- `onReady`
- `onStateChange`
- `onError`
- `onProgress`
- `onPlaybackRateChange`
- `onPlaybackQualityChange`
- `onAutoplayBlocked`

Wrap event handlers with `useCallback` to avoid unstable callback references.

## Ref methods

- `play`, `pause`, `stop`, `seekTo`
- `setVolume`, `getVolume`, `mute`, `unMute`, `isMuted`
- `getCurrentTime`, `getDuration`, `getVideoUrl`, `getVideoEmbedCode`
- `getPlaybackRate`, `setPlaybackRate`, `getAvailablePlaybackRates`
- `getPlayerState`, `getVideoLoadedFraction`
- `loadVideoById`, `cueVideoById`, `setSize`

## Metadata hook

`useYoutubeOEmbed(url?)` fetches optional YouTube oEmbed metadata for a YouTube URL.

## New projects

1.x is legacy. New projects should start with the [2.x API reference](/1.x/guide/usage/api-reference.md) and `useYouTubePlayer` + `YoutubeView`.



---
url: /1.x/guide/migration-from-1.x.md
---

# Migrate to 2.x

Version 2.x replaces the old component/ref model with a hook-and-view model.

> \[!tip]
> This page is a short migration note for readers inside the 1.x docs. For the full and latest migration guide, see the <a href="/guide/migration-from-1.x.html">2.x migration from 1.x guide</a>.

| 1.x                         | 2.x                                |
| --------------------------- | ---------------------------------- |
| `YoutubePlayer` component   | `useYouTubePlayer` + `YoutubeView` |
| callback props              | `useYouTubeEvent`                  |
| `ref.current?.play()`       | `player.play()`                    |
| component props hold config | hook config holds player options   |

## Component replacement

Before:

```tsx
import { YoutubePlayer } from 'react-native-youtube-bridge';

<YoutubePlayer source="AbZH7XWDW_k" />;
```

After:

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

const player = useYouTubePlayer('AbZH7XWDW_k');

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

## Event migration

Before:

```tsx
<YoutubePlayer onReady={handleReady} onStateChange={handleStateChange} />
```

After:

```tsx
useYouTubeEvent(player, 'ready', handleReady);
useYouTubeEvent(player, 'stateChange', handleStateChange);
```

## Control migration

Before:

```tsx
playerRef.current?.play();
```

After:

```tsx
player.play();
```



---
url: /1.x/index.md
---