TypeScript icon, indicating that this package has built-in type declarations

0.1.7 • Public • Published

Youtube Player Plus ✨

Youtube Player Plus is an easy-to-use and customizable library for embedding video playback from Youtube in your web application.

Inspired by this package: yt-player

MIT License NPM version Downloads image


  • 🌐 Utilizes the YouTube IFrame Player API
  • ⚡️ Offers an incredibly fast initial loading time
    • Automatically loads the YouTube IFrame API <script> during first use
    • For an even quicker start, include <script src='' defer></script> in your webpage
    • Ensures API <script> isn't loaded twice by detecting its presence
  • 🚀 API commands are smoothly queued up (wait until both IFrame API and Player instance are ready)
  • ⚠️  Distinguishes between serious errors and unplayable video issues
  • ⏲️ Incorporates the crucial 'timeupdate' event that YouTube API is missing
  • 💡 Clear and detailed code comments for easy comprehension
  • 💯 Strongly typed.
  • 📦 Does not rely on large dependencies or unnecessary code


Use the package manager npm to install youtube-player-plus.

 npm i youtube-player-plus


Quick Start

1.  Install and import YouTubePlayerPlus:

import YouTubePlayerPlus from 'youtube-player-plus';

2.  Create an instance with an element reference and an optional config object:

const element = 'your-element-selector'; // Or an HTMLElement reference
const options = {}; // Optional configuration object
const player = new YouTubePlayerPlus(element, options);

3.  Load a video and control playback:

player.load(videoId, autoplay, start);;

4.  Listen to events:

import type { YTAPI_PlaybackQuality, YTAPI_PlaybackRate } from 'youtube-player-plus/types'

player.on('playing', () => {});

player.on('timeupdate', (current_time: number) => {
    console.log('Current time:', current_time);

player.on('playbackQualityChange', (quality: YTAPI_PlaybackQuality) => {
    console.log('Player quality changed to', quality)

player.on('playbackRateChange', (rate: YTAPI_PlaybackRate) => {
    console.log('Player rate changed to', rate)


YouTubePlayerPlus(element: HTMLElement | string, options?: YT_IFRAME_OPTIONS)


element : HTMLElement or CSS selector - Target element or CSS selector where the YouTube player will be initialized.

options : Object - Optional configuration object for the YouTube player, default values specified below:

Property Type DefaultValue Description
width number 640 The width of the player
height number 360 The height of the player
autoplay boolean false Determines if the video should autoplay when loaded
captions string undefined Sets the default language for captions
controls boolean true Indicates whether the video player controls are displayed
keyboard boolean true Enables/disables keyboard controls
fullscreen boolean true Determines if the fullscreen button is displayed in the player
annotations boolean true Displays video annotations by default
modestBranding boolean false Hides the YouTube logo in the control bar
relatedVideos boolean true Shows related videos from the same channel (0) or any channel (1) when playback ends
timeUpdateFrequency number 0 Determines the frequency (in ms) of 'timeupdate' events being emitted
playsInline boolean true Controls whether videos play inline or fullscreen on iOS
start number 0 Sets the start time of the video in seconds
debug boolean false Enables debug mode which logs additional messages to console
host string '' Determines the hostname where videos are loaded from


Method Description
load(videoId: string, autoplay?: boolean, start?: number) Load the YouTube video.
play() Play the loaded video.
pause() Pause the loaded video.
stop() Stop the loaded video.
seek(seconds: number) Set the current playback time in seconds.
setVolume(volume: number) Sets the player volume.
getVolume(): number Gets the current player volume.
mute() Mutes the player.
unMute() Unmutes the player.
isMuted(): boolean Get the current mute state of the player.
setSize(width: number, height: number) Set the player's size, using the provided width and height values.
getSize(): {width: number, height: number} Get the current player size.
setPlaybackRate(rate: number) Sets the playback rate.
getPlaybackRate(): number Gets the current playback rate.
getAvailablePlaybackRates(): number[] Get a list of available playback rates.
setPlaybackQuality(suggestedQuality: YT_PLAYBACK_QUALITIES) Sets the suggested playback quality.
getPlaybackQuality(): string Gets the current playback quality.
getAvailablePlaybackQualities(): string[] Get a list of available playback qualities.
getDuration(): number Gets the total video duration in seconds.
getProgress(): number Gets the loaded video fraction, ranging from 0 to 1.
getState(): string Gets the current player state.
getYouTubeInstance(): object Gets the currently used YouTube Player API instance, if available.
getPercentageWatched(): number Gets the percentage of the video watched relative to the total duration, 0 to 1.
getCurrentTime(): number It returns the current time of the video in seconds.
destroy() Destroys the player instance and removes event listeners.


Property Getter Setter Description
currentTime Get or set the current playback time in seconds.
volume Get or set the player volume.
muted Get or set the mute state of the player.
size Get or set the player size with a given width and height; retrieves the current size.
playbackRate Get or set the playback rate.
playbackQuality Get or set the current/suggested playback quality.
availablePlaybackQualities   Get a list of available playback qualities.
availablePlaybackRates   Get a list of available playback rates.
duration   Gets the total video duration in seconds.
progress   Gets the loaded video fraction, ranging from 0 to 1.
state   Gets the current player state.
youTubeInstance   Gets the currently used YouTube Player API instance, if available.
percentageWatched   Gets the percentage of the video watched relative to the total duration, 0 to 1.


Event Data
error error: Error
unplayable videoId: string
timeupdate currentTime: number
playbackQualityChange quality: YTAPI_PlaybackQuality
playbackRateChange rate: YTAPI_PlaybackRate

Listen to events

To listen to an event:

player.on('event-name', (eventData) => {
  // Your event handling logic here

To stop listening to an event:

player.removeListener('event-name', eventHandlerFunction);



Pull requests are welcome. For major changes, please open an issue first
to discuss what you would like to change.

Please make sure to update tests as appropriate.



Package Sidebar


npm i youtube-player-plus

Weekly Downloads






Unpacked Size

42.9 kB

Total Files


Last publish


  • maarcosv99