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

Click to load
Props
The ScriptYouTubePlayer
component accepts the following props:
trigger
: The trigger event to load the YouTube Player. Default ismousedown
. 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 isfalse
.
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
}
Privacy
The <YoutubePlayer>
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 completely 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]
}>()
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>