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