YouTube Player

YouTube is a video hosting platform that allows you to upload and share videos.

Nuxt Scripts provides a useScriptYouTubePlayer composable and a headless ScriptYouTubePlayer component to interact with the YouTube Player.

ScriptYouTubePlayer

The ScriptYouTubePlayer component is a wrapper around the useScriptYouTubePlayer composable. It provides a simple way to embed YouTube videos in your Nuxt app.

It's optimized for performance by leveraging the Element Event Triggers, only loading the YouTube Player when the specific elements events happen.

By default, it will load on the mousedown event.

Demo

OutputInput

Click to load

Clicking the video will load the YouTube iframe and start the video.

Props

The ScriptYouTubePlayer component accepts the following props:

• trigger: The trigger event to load the YouTube Player. Default is mousedown. See Element Event Triggers for more information.
• placeholderAttrs: The attributes for the placeholder image. Default is { loading: 'lazy' }.
• aboveTheFold: Optimizes the placeholder image for above-the-fold content. Default is false.

All script options from the YouTube IFrame Player API are supported on the playerVars prop, please consult the Supported paramters for full documentation.

export interface YouTubeProps {
  // YouTube Player
  videoId: string
  playerVars?: YT.PlayerVars
  width?: number
  height?: number
}

Eager Loading Placeholder

The YouTube Player placeholder image is lazy-loaded by default. You should change this behavior if your video is above the fold or consider using the #placeholder slot to customize the placeholder image.

<ScriptYouTubePlayer above-the-fold />

Component API

See the Facade Component API for full props, events, and slots.

Events

The ScriptYouTubePlayer component emits all events from the YouTube Player SDK. Please consult the Player Events for full documentation.

const emits = defineEmits<{
  'ready': [e: YT.PlayerEvent]
  'state-change': [e: YT.OnStateChangeEvent, target: YT.Player]
  'playback-quality-change': [e: YT.OnPlaybackQualityChangeEvent, target: YT.Player]
  'playback-rate-change': [e: YT.OnPlaybackRateChangeEvent, target: YT.Player]
  'error': [e: YT.OnErrorEvent, target: YT.Player]
}>()

Slots

As the component is provided headless, there are a number of slots for you to customize the player however you like before it's loaded in.

default

The default slot is used to display content that will always be visible.

<template>
  <ScriptYouTubePlayer video-id="d_IFKP1Ofq0">
    <div class="bg-blue-500 text-white p-5">
      Video by Nuxt
    </div>
  </ScriptYouTubePlayer>
</template>

awaitingLoad

The slot is used to display content while the video is loading.

<template>
  <ScriptYouTubePlayer video-id="d_IFKP1Ofq0">
    <template #awaitingLoad>
      <div class="bg-blue-500 text-white p-5">
        Click to play!
      </div>
    </template>
  </ScriptYouTubePlayer>
</template>

loading

The slot is used to display content while the video is loading.

<template>
  <ScriptYouTubePlayer video-id="d_IFKP1Ofq0">
    <template #loading>
      <div class="bg-blue-500 text-white p-5">
        Loading...
      </div>
    </template>
  </ScriptYouTubePlayer>
</template>

placeholder

The slot is used to display a placeholder image before the video is loaded. By default, this will show the youtube thumbnail for the video. You can display it however you like.

<template>
  <ScriptYouTubePlayer video-id="d_IFKP1Ofq0">
    <template #placeholder="{ placeholder }">
      <img :src="placeholder" alt="Video Placeholder">
    </template>
  </ScriptYouTubePlayer>
</template>

useScriptYouTubePlayer

The useScriptYouTubePlayer composable lets you have fine-grain control over the YouTube Player SDK. It provides a way to load the YouTube Player SDK and interact with it programmatically.

export function useScriptYouTubePlayer<T extends YouTubePlayerApi>(_options?: YouTubePlayerInput) {}

Please follow the Registry Scripts guide to learn more about advanced usage.

YouTubePlayerApi

/// <reference types="youtube" />
export interface YouTubePlayerApi {
  YT: typeof YT
}

Example

Loading the YouTube Player SDK and interacting with it programmatically.

<script setup lang="ts">
const video = ref()
const { onLoaded } = useScriptYouTubePlayer()

const player = ref(null)
onLoaded(async ({ YT }) => {
  // we need to wait for the internal YouTube APIs to be ready
  const YouTube = await YT
  await new Promise<void>((resolve) => {
    if (typeof YT.Player === 'undefined')
      YouTube.ready(resolve)
    else
      resolve()
  })
  // load the API
  player.value = new YT.Player(video.value, {
    videoId: 'd_IFKP1Ofq0'
  })
})
function play() {
  player.value?.playVideo()
}
</script>

<template>
  <div>
    <div ref="video" />
    <button @click="play">
      Play
    </button>
  </div>
</template>