Scripts

YouTube Player

Copy for LLMs

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.

YouTube Player

View source

Nuxt Config Setup

The simplest way to load YouTube Player globally in your Nuxt App is to use Nuxt config. Alternatively you can directly use the useScriptYouTubePlayer composable. 

export default defineNuxtConfig({
  scripts: {
    registry: {
      youtubePlayer: true
    }
  }
})

useScriptYouTubePlayer()

The useScriptYouTubePlayer composable lets you have fine-grain control over when and how YouTube Player is loaded on your site. 

const { proxy } = useScriptYouTubePlayer()

const { YT } = await proxy

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

First-Party Mode

This script supports First-Party Mode which is auto-enabled, routing all traffic through your domain for improved privacy and ad blocker bypass. 

export default defineNuxtConfig({
  scripts: {
    registry: {
      youtubePlayer: true
    }
  }
})

Example

Using YouTube Player only in production while using the proxy to send events. 

<script setup lang="ts">
const { proxy } = useScriptYouTubePlayer()

// noop in development, ssr
// just works in production, client
function handleAction() {
  const { YT } = await proxy
}
</script>

<template>
  <div>
    <button @click="handleAction">
      Send Event
    </button>
  </div>
</template>

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.

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

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.