Scripts

YouTube Player

Copy for LLMs
Last updated by Harlan Wilton in chore: lint.

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.

Script Stats
Transfer
14.0 KB
Decoded
32.4 KB
Loading
CDN
First-Party
No
Bundling
No
Tracked Data
Video Engagement
export interface YouTubePlayerApi {
  YT: MaybePromise<{
    Player: YT.Player
    PlayerState: YT.PlayerState
    get: (k: string) => any
    loaded: 0 | 1
    loading: 0 | 1
    ready: (f: () => void) => void
    scan: () => void
    setConfig: (config: YT.PlayerOptions) => void
    subscribe: <EventName extends keyof YT.Events>(
      event: EventName,
      listener: YT.Events[EventName],
      context?: any,
    ) => void
    unsubscribe: <EventName extends keyof YT.Events>(
      event: EventName,
      listener: YT.Events[EventName],
      context?: any,
    ) => void
  }>
}

Types

To use YouTube with full TypeScript support, you will need to install the @types/youtube dependency.

pnpm add -D @types/youtube

<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 using 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

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

Privacy

The <ScriptYouTubePlayer> component is privacy-friendly by default and sets the video host to https://www.youtube-nocookie.com.

To modify this behavior, you can set the host prop to https://www.youtube.com.

<ScriptYouTubePlayer video-id="d_IFKP1Ofq0" :player-options="{ host: 'https://www.youtube.com' }" />

Placeholder

The YouTube Player placeholder image is 1280x720 webp that is lazy-loaded by default.

To modify the placeholder size you can set the thumbnailSize prop, if you'd prefer to use a jpg you can pass the webp prop as false.

<ScriptYouTubePlayer video-id="d_IFKP1Ofq0" thumbnail-size="maxresdefault" />

If you need fine control over the placeholder you can set placeholderAttrs prop or override it using the #placeholder slot.

Eager Loading

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]
  'api-change': [e: YT.PlayerEvent, target: YT.Player]
}>()

Slots

As Nuxt provides the component headless, you can use slots to customize the player however you like before it loads.

default

The default slot displays 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

This slot displays 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

This slot displays 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

This slot displays a placeholder image before the video loads. 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.

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>
Edit this page
Markdown For LLMs

X Pixel

Use X Pixel in your Nuxt app.