0
# TipTap YouTube Extension
1

2
The TipTap YouTube Extension provides comprehensive YouTube video embedding capabilities for TipTap editors. It enables embedding YouTube videos with extensive configuration options for video behavior, appearance, and integration.
3

4
## Package Information
5

6
- **Package Name**: @tiptap/extension-youtube
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tiptap/extension-youtube`
10

11
## Core Imports
12

13
```typescript
14
import { Youtube } from "@tiptap/extension-youtube";
15
import { YoutubeOptions } from "@tiptap/extension-youtube";
16
```
17

18
Default import:
19

20
```typescript
21
import Youtube from "@tiptap/extension-youtube";
22
```
23

24
## Basic Usage
25

26
```typescript
27
import { Editor } from "@tiptap/core";
28
import { Youtube } from "@tiptap/extension-youtube";
29

30
// Create editor with YouTube extension
31
const editor = new Editor({
32
  extensions: [
33
    Youtube.configure({
34
      width: 800,
35
      height: 450,
36
      controls: true,
37
      allowFullscreen: true,
38
    }),
39
  ],
40
});
41

42
// Insert YouTube video
43
editor.commands.setYoutubeVideo({
44
  src: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
45
  width: 800,
46
  height: 450,
47
});
48
```
49

50
## Architecture
51

52
The TipTap YouTube Extension is built as a TipTap Node extension that integrates with the TipTap editor framework:
53

54
- **Node Extension**: Implements the TipTap Node interface to provide YouTube video embedding functionality
55
- **Command Integration**: Adds the `setYoutubeVideo` command to the editor's command system
56
- **Paste Handler**: Automatically converts pasted YouTube URLs into embedded videos
57
- **HTML Rendering**: Generates iframe-based embed code with configurable parameters
58
- **Type Safety**: Full TypeScript support with comprehensive option interfaces
59

60
## Capabilities
61

62
### YouTube Node Extension
63

64
The main TipTap node extension for embedding YouTube videos with comprehensive configuration options.
65

66
```typescript { .api }
67
/**
68
 * YouTube node extension for TipTap editor
69
 */
70
const Youtube: Node<YoutubeOptions>;
71

72
interface YoutubeOptions {
73
  /** Controls if the paste handler for youtube videos should be added (default: true) */
74
  addPasteHandler: boolean;
75
  /** Controls if the youtube video should be allowed to go fullscreen (default: true) */
76
  allowFullscreen: boolean;
77
  /** Controls if the youtube video should autoplay (default: false) */
78
  autoplay: boolean;
79
  /** The language of the captions shown in the youtube video (default: undefined) */
80
  ccLanguage?: string;
81
  /** Controls if the captions should be shown in the youtube video (default: undefined) */
82
  ccLoadPolicy?: boolean;
83
  /** Controls if the controls should be shown in the youtube video (default: true) */
84
  controls: boolean;
85
  /** Controls if the keyboard controls should be disabled in the youtube video (default: false) */
86
  disableKBcontrols: boolean;
87
  /** Controls if the iframe api should be enabled in the youtube video (default: false) */
88
  enableIFrameApi: boolean;
89
  /** The end time of the youtube video (default: 0) */
90
  endTime: number;
91
  /** The height of the youtube video (default: 480) */
92
  height: number;
93
  /** The language of the youtube video (default: undefined) */
94
  interfaceLanguage?: string;
95
  /** Controls if the video annotations should be shown in the youtube video (default: 0) */
96
  ivLoadPolicy: number;
97
  /** Controls if the youtube video should loop (default: false) */
98
  loop: boolean;
99
  /** Controls if the youtube video should show a small youtube logo (default: false) */
100
  modestBranding: boolean;
101
  /** The HTML attributes for a youtube video node (default: {}) */
102
  HTMLAttributes: Record<string, any>;
103
  /** Controls if the youtube node should be inline or not (default: false) */
104
  inline: boolean;
105
  /** Controls if the youtube video should be loaded from youtube-nocookie.com (default: false) */
106
  nocookie: boolean;
107
  /** The origin of the youtube video (default: '') */
108
  origin: string;
109
  /** The playlist of the youtube video (default: '') */
110
  playlist: string;
111
  /** The color of the youtube video progress bar (default: undefined) */
112
  progressBarColor?: string;
113
  /** The width of the youtube video (default: 640) */
114
  width: number;
115
  /** Controls if the related youtube videos at the end are from the same channel (default: 1) */
116
  rel: number;
117
}
118
```
119

120
### YouTube Video Command
121

122
Command to insert YouTube videos into the TipTap editor.
123

124
```typescript { .api }
125
/**
126
 * Command to insert a YouTube video node
127
 * Available as editor.commands.setYoutubeVideo()
128
 * Returns true if successful, false if URL is invalid
129
 */
130
setYoutubeVideo(options: {
131
  /** YouTube video URL */
132
  src: string;
133
  /** Optional width override */
134
  width?: number;
135
  /** Optional height override */
136
  height?: number;
137
  /** Optional start time in seconds */
138
  start?: number;
139
}): boolean;
140
```
141

142
**Usage Example:**
143

144
```typescript
145
// Insert a YouTube video with custom dimensions
146
const success = editor.commands.setYoutubeVideo({
147
  src: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
148
  width: 800,
149
  height: 450,
150
  start: 30, // Start at 30 seconds
151
});
152

153
if (success) {
154
  console.log("Video inserted successfully");
155
} else {
156
  console.error("Invalid YouTube URL");
157
}
158

159
// Insert with default dimensions
160
editor.commands.setYoutubeVideo({
161
  src: "https://youtu.be/dQw4w9WgXcQ",
162
});
163
```
164

165

166

167

168

169
## Configuration Examples
170

171
### Basic Configuration
172

173
```typescript
174
import { Youtube } from "@tiptap/extension-youtube";
175

176
// Basic setup with default options
177
const editor = new Editor({
178
  extensions: [Youtube],
179
});
180
```
181

182
### Advanced Configuration
183

184
```typescript
185
import { Youtube } from "@tiptap/extension-youtube";
186

187
// Advanced configuration with custom options
188
const editor = new Editor({
189
  extensions: [
190
    Youtube.configure({
191
      // Video dimensions
192
      width: 800,
193
      height: 450,
194
      
195
      // Privacy and branding
196
      nocookie: true,
197
      modestBranding: true,
198
      
199
      // Playback behavior
200
      autoplay: false,
201
      loop: false,
202
      controls: true,
203
      
204
      // Captions and language
205
      ccLanguage: "en",
206
      ccLoadPolicy: true,
207
      interfaceLanguage: "en",
208
      
209
      // Related videos and annotations
210
      rel: 0, // Hide related videos
211
      ivLoadPolicy: 0, // Hide annotations
212
      
213
      // Additional features
214
      enableIFrameApi: true,
215
      allowFullscreen: true,
216
      disableKBcontrols: false,
217
      
218
      // Custom HTML attributes
219
      HTMLAttributes: {
220
        class: "youtube-video",
221
        "data-testid": "youtube-embed",
222
      },
223
      
224
      // Paste handling
225
      addPasteHandler: true,
226
    }),
227
  ],
228
});
229
```
230

231
### Inline YouTube Videos
232

233
```typescript
234
import { Youtube } from "@tiptap/extension-youtube";
235

236
// Configure for inline display
237
const editor = new Editor({
238
  extensions: [
239
    Youtube.configure({
240
      inline: true,
241
      width: 320,
242
      height: 180,
243
    }),
244
  ],
245
});
246
```
247

248
## Error Handling
249

250
The extension handles various error scenarios:
251

252
- **Invalid URLs**: `setYoutubeVideo` returns `false` for invalid YouTube URLs
253
- **Network Issues**: Embedded videos handle loading errors through YouTube's iframe
254
- **Configuration Errors**: Invalid options fall back to defaults
255

256
```typescript
257
// Check if video insertion was successful
258
const success = editor.commands.setYoutubeVideo({
259
  src: "invalid-url"
260
});
261

262
if (!success) {
263
  console.error("Failed to insert YouTube video - invalid URL");
264
}
265

266
// The extension internally validates URLs before insertion
267
const url = "https://www.youtube.com/watch?v=dQw4w9WgXcQ";
268
const result = editor.commands.setYoutubeVideo({ src: url });
269
if (!result) {
270
  console.error("Invalid YouTube URL");
271
}
272
```