0
# Tiptap Extension Youtube
1

2
A YouTube video embedding extension for the Tiptap rich text editor framework. Built as a ProseMirror node extension, it enables developers to seamlessly embed YouTube videos within rich text documents with comprehensive configuration options including autoplay controls, caption settings, keyboard navigation, fullscreen capabilities, and custom styling parameters.
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
```
16

17
For default import:
18

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

23
CommonJS:
24

25
```javascript
26
const { Youtube } = require("@tiptap/extension-youtube");
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { Editor } from '@tiptap/core';
33
import { Youtube } from '@tiptap/extension-youtube';
34

35
const editor = new Editor({
36
  extensions: [
37
    Youtube.configure({
38
      width: 480,
39
      height: 320,
40
      nocookie: true, // Use youtube-nocookie.com for privacy
41
    }),
42
  ],
43
});
44

45
// Insert a YouTube video
46
editor.commands.setYoutubeVideo({
47
  src: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
48
  width: 640,
49
  height: 480,
50
});
51
```
52

53
## Architecture
54

55
The extension is built around several key components:
56

57
- **Node Extension**: Core `Youtube` node extending Tiptap's Node class for rich text integration
58
- **URL Processing**: Intelligent parsing and validation for various YouTube URL formats
59
- **Configuration System**: Comprehensive options for controlling video behavior and appearance
60
- **Paste Handler**: Automatic conversion of pasted YouTube URLs to embedded videos
61
- **Command Interface**: Programmatic API for inserting YouTube videos via editor commands
62

63
## Capabilities
64

65
### YouTube Node Extension
66

67
The main extension for embedding YouTube videos in Tiptap editors.
68

69
```typescript { .api }
70
/**
71
 * YouTube video embedding extension for Tiptap
72
 */
73
const Youtube: Node<YoutubeOptions>;
74

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

123
**Usage Examples:**
124

125
```typescript
126
import { Editor } from '@tiptap/core';
127
import { Youtube } from '@tiptap/extension-youtube';
128

129
// Basic configuration
130
const editor = new Editor({
131
  extensions: [
132
    Youtube.configure({
133
      width: 640,
134
      height: 480,
135
      nocookie: true,
136
    }),
137
  ],
138
});
139

140
// Advanced configuration with privacy and accessibility features
141
const editor = new Editor({
142
  extensions: [
143
    Youtube.configure({
144
      width: 800,
145
      height: 450,
146
      autoplay: false,
147
      controls: true,
148
      disableKBcontrols: false,
149
      allowFullscreen: true,
150
      nocookie: true, // GDPR-friendly
151
      modestBranding: true,
152
      ccLanguage: 'en',
153
      ccLoadPolicy: true,
154
      progressBarColor: 'red',
155
      rel: 0, // Don't show related videos from other channels
156
    }),
157
  ],
158
});
159
```
160

161
### YouTube Video Commands
162

163
Commands for programmatically inserting YouTube videos.
164

165
```typescript { .api }
166
/**
167
 * Insert a YouTube video into the editor
168
 * @param options Video configuration options
169
 * @returns Command that returns boolean indicating success/failure
170
 */
171
setYoutubeVideo(options: {
172
  /** YouTube video URL (required) */
173
  src: string;
174
  /** Video width in pixels (optional) */
175
  width?: number;
176
  /** Video height in pixels (optional) */
177
  height?: number;
178
  /** Start time in seconds (optional) */
179
  start?: number;
180
}): boolean;
181
```
182

183
**Usage Examples:**
184

185
```typescript
186
// Insert a video with basic options
187
const success = editor.commands.setYoutubeVideo({
188
  src: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
189
});
190

191
// Insert a video with custom dimensions and start time
192
const result = editor.commands.setYoutubeVideo({
193
  src: 'https://youtu.be/dQw4w9WgXcQ',
194
  width: 800,
195
  height: 450,
196
  start: 30, // Start at 30 seconds
197
});
198

199
// Insert a video from various YouTube URL formats
200
const inserted = editor.commands.setYoutubeVideo({
201
  src: 'https://youtube-nocookie.com/watch?v=dQw4w9WgXcQ',
202
});
203
```
204

205

206
## Supported URL Formats
207

208
The extension supports various YouTube URL formats:
209

210
- `https://www.youtube.com/watch?v=VIDEO_ID`
211
- `https://youtu.be/VIDEO_ID`
212
- `https://youtube-nocookie.com/watch?v=VIDEO_ID`
213
- `https://m.youtube.com/watch?v=VIDEO_ID`
214
- `https://music.youtube.com/watch?v=VIDEO_ID`
215
- YouTube playlist URLs with `list` parameter
216
- YouTube Shorts URLs
217

218
## Error Handling
219

220
The extension handles invalid URLs gracefully:
221

222
- `setYoutubeVideo` command returns `false` for invalid URLs and doesn't insert content
223
- Invalid YouTube URLs are rejected and will not be embedded
224

225
## Types
226

227
```typescript { .api }
228
/**
229
 * Configuration options for the YouTube extension
230
 */
231
interface YoutubeOptions {
232
  addPasteHandler: boolean;
233
  allowFullscreen: boolean;
234
  autoplay: boolean;
235
  ccLanguage?: string;
236
  ccLoadPolicy?: boolean;
237
  controls: boolean;
238
  disableKBcontrols: boolean;
239
  enableIFrameApi: boolean;
240
  endTime: number;
241
  height: number;
242
  interfaceLanguage?: string;
243
  ivLoadPolicy: number;
244
  loop: boolean;
245
  modestBranding: boolean;
246
  HTMLAttributes: Record<string, any>;
247
  inline: boolean;
248
  nocookie: boolean;
249
  origin: string;
250
  playlist: string;
251
  progressBarColor?: string;
252
  width: number;
253
  rel: number;
254
}
255
256
```