0
# Component System
1

2
Video.js uses a hierarchical component system where all UI elements inherit from a base Component class. This enables building custom player interfaces and extending functionality through reusable components.
3

4
## Capabilities
5

6
### Component Registration
7

8
Register custom components for use in players and extend the component system.
9

10
```javascript { .api }
11
/**
12
 * Register a custom component for use in players
13
 * @param name - Component name (used in player options and addChild calls)
14
 * @param component - Component class extending Component
15
 * @returns Registered component class
16
 */
17
videojs.registerComponent(name: string, component: typeof Component): typeof Component;
18

19
/**
20
 * Get registered component class by name
21
 * @param name - Component name
22
 * @returns Component class or undefined
23
 */
24
videojs.getComponent(name: string): typeof Component | undefined;
25
```
26

27
**Usage Examples:**
28

29
```javascript
30
// Create custom component
31
class CustomButton extends videojs.getComponent('Button') {
32
  constructor(player, options) {
33
    super(player, options);
34
    this.controlText('Custom Action');
35
  }
36
  
37
  handleClick() {
38
    console.log('Custom button clicked!');
39
  }
40
}
41

42
// Register component
43
videojs.registerComponent('CustomButton', CustomButton);
44

45
// Use in player
46
const player = videojs('my-video', {
47
  children: ['CustomButton']
48
});
49

50
// Or add programmatically
51
const customButton = new CustomButton(player);
52
player.addChild(customButton);
53
```
54

55
### Base Component Class
56

57
Core component functionality providing DOM management, event handling, and child component support.
58

59
```javascript { .api }
60
/**
61
 * Base class for all UI components
62
 */
63
class Component {
64
  /**
65
   * Create component instance
66
   * @param player - Player instance
67
   * @param options - Component options
68
   */
69
  constructor(player?: Player, options?: ComponentOptions);
70
  
71
  /**
72
   * Get component's DOM element
73
   * @returns Component's DOM element
74
   */
75
  el(): Element;
76
  
77
  /**
78
   * Get/set component content text
79
   * @param text - Text content to set
80
   * @returns Current text or this for chaining
81
   */
82
  contentEl(): Element;
83
  
84
  /**
85
   * Get component ID
86
   * @returns Component ID
87
   */
88
  id(): string;
89
  
90
  /**
91
   * Get component name
92
   * @returns Component name
93
   */
94
  name(): string;
95
  
96
  /**
97
   * Get associated player
98
   * @returns Player instance
99
   */
100
  player(): Player;
101
  
102
  /**
103
   * Get component options
104
   * @returns Component options
105
   */
106
  options(): ComponentOptions;
107
}
108
```
109

110
### Child Component Management
111

112
Manage hierarchical component relationships with dynamic addition and removal.
113

114
```javascript { .api }
115
/**
116
 * Add child component
117
 * @param child - Component name, instance, or class
118
 * @param options - Child component options  
119
 * @param index - Index to insert at
120
 * @returns Child component instance
121
 */
122
addChild(child: string | Component | typeof Component, options?: object, index?: number): Component;
123

124
/**
125
 * Remove child component
126
 * @param component - Child component to remove
127
 */
128
removeChild(component: Component): void;
129

130
/**
131
 * Initialize child components from options
132
 * @param children - Array of child component definitions
133
 */
134
initChildren(children?: ChildComponentSpec[]): void;
135

136
/**
137
 * Get child component by name
138
 * @param name - Child component name
139
 * @returns Child component or undefined
140
 */
141
getChild(name: string): Component | undefined;
142

143
/**
144
 * Get child component by ID
145
 * @param id - Child component ID
146
 * @returns Child component or undefined
147
 */
148
getChildById(id: string): Component | undefined;
149

150
/**
151
 * Get all child components
152
 * @returns Array of child components
153
 */
154
children(): Component[];
155
```
156

157
**Usage Examples:**
158

159
```javascript
160
// Add child components
161
const controlBar = player.getChild('ControlBar');
162
const customButton = controlBar.addChild('CustomButton', {
163
  text: 'My Button'
164
});
165

166
// Remove child
167
controlBar.removeChild(customButton);
168

169
// Get children
170
const playButton = controlBar.getChild('PlayToggle');
171
const allChildren = controlBar.children();
172
```
173

174
### Event Handling
175

176
Component-level event handling with automatic cleanup and delegation support.
177

178
```javascript { .api }
179
/**
180
 * Add event listener
181
 * @param type - Event type or types (space-separated)
182
 * @param listener - Event handler function
183
 */
184
on(type: string, listener: EventListener): void;
185

186
/**
187
 * Add one-time event listener  
188
 * @param type - Event type or types (space-separated)
189
 * @param listener - Event handler function
190
 */
191
one(type: string, listener: EventListener): void;
192

193
/**
194
 * Remove event listener
195
 * @param type - Event type or types (space-separated)
196
 * @param listener - Event handler function to remove
197
 */
198
off(type?: string, listener?: EventListener): void;
199

200
/**
201
 * Trigger event on component
202
 * @param event - Event type or Event object
203
 * @param data - Event data
204
 */
205
trigger(event: string | Event, data?: any): void;
206
```
207

208
**Usage Examples:**
209

210
```javascript
211
// Add event listeners
212
component.on('click', function(event) {
213
  console.log('Component clicked');
214
});
215

216
component.on('focus blur', function(event) {
217
  console.log('Focus changed:', event.type);
218
});
219

220
// One-time listener
221
component.one('ready', function() {
222
  console.log('Component ready - fires once');
223
});
224

225
// Trigger custom events
226
component.trigger('customEvent', { data: 'value' });
227

228
// Remove listeners
229
component.off('click'); // Remove all click listeners
230
component.off(); // Remove all listeners
231
```
232

233
### DOM and Styling
234

235
DOM manipulation and CSS class management for component styling.
236

237
```javascript { .api }
238
/**
239
 * Add CSS class
240
 * @param className - Class name to add
241
 */
242
addClass(className: string): void;
243

244
/**
245
 * Remove CSS class
246
 * @param className - Class name to remove
247
 */
248
removeClass(className: string): void;
249

250
/**
251
 * Toggle CSS class
252
 * @param className - Class name to toggle
253
 * @param predicate - Force add (true) or remove (false)
254
 */
255
toggleClass(className: string, predicate?: boolean): void;
256

257
/**
258
 * Check if component has CSS class
259
 * @param className - Class name to check
260
 * @returns True if class exists
261
 */
262
hasClass(className: string): boolean;
263

264
/**
265
 * Show component
266
 */
267
show(): void;
268

269
/**
270
 * Hide component
271
 */
272
hide(): void;
273

274
/**
275
 * Get/set component width
276
 * @param width - Width to set
277
 * @returns Current width or this for chaining
278
 */
279
width(width?: number | string): number | Component;
280

281
/**
282
 * Get/set component height
283
 * @param height - Height to set
284
 * @returns Current height or this for chaining
285
 */
286
height(height?: number | string): number | Component;
287
```
288

289
### Lifecycle Management
290

291
Component lifecycle methods for initialization, ready state, and cleanup.
292

293
```javascript { .api }
294
/**
295
 * Execute callback when component is ready
296
 * @param callback - Function to call when ready
297
 */
298
ready(callback: () => void): void;
299

300
/**
301
 * Dispose component and clean up resources
302
 */
303
dispose(): void;
304

305
/**
306
 * Check if component has been disposed
307
 * @returns True if disposed
308
 */
309
isDisposed(): boolean;
310

311
/**
312
 * Get component's ready state
313
 * @returns True if ready
314
 */
315
isReady(): boolean;
316
```
317

318
### Built-in Components
319

320
Video.js includes many built-in components that can be extended or customized.
321

322
```javascript { .api }
323
// Control Bar Components
324
ControlBar: typeof Component;
325
PlayToggle: typeof Component;
326
MuteToggle: typeof Component;
327
VolumeControl: typeof Component;
328
ProgressControl: typeof Component;
329
FullscreenToggle: typeof Component;
330
PictureInPictureToggle: typeof Component;
331

332
// Menu Components  
333
Menu: typeof Component;
334
MenuItem: typeof Component;
335
MenuButton: typeof Component;
336

337
// UI Components
338
Button: typeof Component;
339
BigPlayButton: typeof Component;
340
LoadingSpinner: typeof Component;
341
ErrorDisplay: typeof Component;
342
PosterImage: typeof Component;
343

344
// Text Track Components
345
TextTrackDisplay: typeof Component;
346
TextTrackSettings: typeof Component;
347
TextTrackMenuItem: typeof Component;
348
```
349

350
**Usage Examples:**
351

352
```javascript
353
// Extend built-in components
354
class CustomPlayButton extends videojs.getComponent('PlayToggle') {
355
  buildCSSClass() {
356
    return `custom-play ${super.buildCSSClass()}`;
357
  }
358
  
359
  handleClick() {
360
    super.handleClick();
361
    console.log('Custom play logic');
362
  }
363
}
364

365
// Replace default component
366
videojs.registerComponent('PlayToggle', CustomPlayButton);
367

368
// Create custom menu
369
class QualityMenu extends videojs.getComponent('MenuButton') {
370
  constructor(player, options) {
371
    super(player, options);
372
    this.controlText('Quality');
373
  }
374
  
375
  createItems() {
376
    return [
377
      new QualityMenuItem(this.player(), { label: '1080p', quality: '1080p' }),
378
      new QualityMenuItem(this.player(), { label: '720p', quality: '720p' }),
379
      new QualityMenuItem(this.player(), { label: '480p', quality: '480p' })
380
    ];
381
  }
382
}
383
```
384

385
## Types
386

387
```javascript { .api }
388
interface ComponentOptions {
389
  [key: string]: any;
390
}
391

392
interface ChildComponentSpec {
393
  name?: string;
394
  component?: string | typeof Component;
395
  options?: ComponentOptions;
396
}
397

398
interface Component {
399
  // Core properties
400
  player_: Player;
401
  options_: ComponentOptions;
402
  el_: Element;
403
  children_: Component[];
404
  
405
  // Lifecycle
406
  ready(callback: () => void): void;
407
  dispose(): void;
408
  isDisposed(): boolean;
409
  
410
  // DOM management
411
  el(): Element;
412
  contentEl(): Element;
413
  addClass(className: string): void;
414
  removeClass(className: string): void;
415
  hasClass(className: string): boolean;
416
  show(): void;
417
  hide(): void;
418
  
419
  // Child management
420
  addChild(child: string | Component, options?: object): Component;
421
  removeChild(component: Component): void;
422
  getChild(name: string): Component | undefined;
423
  children(): Component[];
424
  
425
  // Event handling
426
  on(type: string, listener: EventListener): void;
427
  off(type?: string, listener?: EventListener): void;
428
  trigger(event: string | Event, data?: any): void;
429
}
430
```