Skip to main content

​
Angular YouTube Player

The Angular YouTube Player component provides a simple wrapper around the YouTube Player API for Angular applications. Source: /home/daytona/workspace/source/src/youtube-player/README.md

​
Installation

To install the package, run: 
ng add @angular/youtube-player

​
Basic Usage

import {Component} from '@angular/core';
import {YouTubePlayer} from '@angular/youtube-player';

@Component({
  imports: [YouTubePlayer],
  template: '<youtube-player videoId="mVjYG9TSN88"/>',
  selector: 'youtube-player-example',
})
export class YoutubePlayerExample {}

​
Getting the Video ID

If your video is at https://www.youtube.com/watch?v=mVjYG9TSN88, then your video ID is mVjYG9TSN88.

​
Features

  • Automatic API Loading - The YouTube iframe API is loaded automatically when needed
  • Lazy Loading - Shows a placeholder until user interaction for better performance
  • Type Safety - Full TypeScript support with YouTube Player API types
  • Event Support - All YouTube Player events are available as Angular outputs
  • Flexible Configuration - Control API loading, placeholder behavior, and player settings

​
YouTube iframe API Usage

The <youtube-player/> component requires the YouTube iframe API to work. If the API isn’t loaded by the time the player is initialized, it’ll load the API automatically from https://www.youtube.com/iframe_api.

​
Disable Auto-Loading

You can control API loading on a per-component level: 
<youtube-player videoId="mVjYG9TSN88" loadApi="false"/>
Or globally using the YOUTUBE_PLAYER_CONFIG injection token: 
import {NgModule} from '@angular/core';
import {YouTubePlayer, YOUTUBE_PLAYER_CONFIG} from '@angular/youtube-player';

@NgModule({
  imports: [YouTubePlayer],
  providers: [{
    provide: YOUTUBE_PLAYER_CONFIG,
    useValue: {
      loadApi: false
    }
  }]
})
export class YourApp {}

​
Loading Behavior

By default, the <youtube-player/> shows a placeholder element instead of loading the API up-front until the user interacts with it. This speeds up initial page load by not loading unnecessary JavaScript for a video that might not be played. Once the user clicks on the video, the API will be loaded and the placeholder will be swapped out with the actual video.

​
When Placeholder is NOT Shown

The placeholder won’t be shown in these scenarios:
  • Video that plays automatically (e.g., playerVars contains autoplay: 1)
  • The player is showing a playlist (e.g., playerVars contains a list property)

​
Disable Placeholder

You can disable the placeholder per component: 
<youtube-player videoId="mVjYG9TSN88" disablePlaceholder/>
Or globally: 
import {NgModule} from '@angular/core';
import {YouTubePlayer, YOUTUBE_PLAYER_CONFIG} from '@angular/youtube-player';

@NgModule({
  imports: [YouTubePlayer],
  providers: [{
    provide: YOUTUBE_PLAYER_CONFIG,
    useValue: {
      disablePlaceholder: true
    }
  }]
})
export class YourApp {}

​
Placeholder Image Quality

YouTube provides different sizes of placeholder images depending on when the video was uploaded and the thumbnail provided by the uploader. The <youtube-player/> defaults to a quality that should be available for the majority of videos. If you’re seeing a grey placeholder, consider switching to the low quality: 
<!-- Default value, should exist for most videos -->
<youtube-player videoId="mVjYG9TSN88" placeholderImageQuality="standard"/>

<!-- High quality image that should be present for most videos from the past few years -->
<youtube-player videoId="mVjYG9TSN88" placeholderImageQuality="high"/>

<!-- Very low quality image, but should exist for all videos -->
<youtube-player videoId="mVjYG9TSN88" placeholderImageQuality="low"/>
You can also configure this globally using YOUTUBE_PLAYER_CONFIG.

​
Placeholder Internationalization

The placeholder has an interactive button element that needs an aria-label for proper accessibility. The default label is “Play video”, but you can customize it: 
<youtube-player videoId="mVjYG9TSN88" placeholderButtonLabel="Afspil video"/>
Or globally: 
providers: [{
  provide: YOUTUBE_PLAYER_CONFIG,
  useValue: {
    placeholderButtonLabel: 'Reproducir vídeo'
  }
}]

​
Placeholder Caveats

  1. Variable Image Sizes: Different videos support different sizes of placeholder images and there’s no way to know ahead of time which one is supported. The component defaults to a value that should work for most videos.
  2. No Video Title: Unlike the native YouTube placeholder, the Angular component doesn’t show the video’s title because it isn’t known ahead of time.

​
Repository

File any bugs against the angular/components repo.

​
Source Code

View the YouTube Player source code on GitHub.

Build docs developers (and LLMs) love

Get started for freeTalk to us