Vimeo Player
Vimeo hosts videos and provides a JavaScript player API.
Nuxt Scripts provides a useScriptVimeoPlayer() composable and a headless <ScriptVimeoPlayer> component for interacting with the Vimeo Player.
Nuxt Config Setup
Add this to your nuxt.config.ts to load Vimeo Player globally. Alternatively you can use the useScriptVimeoPlayer composable for more control.
export default defineNuxtConfig({
scripts: {
registry: {
vimeoPlayer: {
trigger: 'onNuxtReady',
}
}
}
})This config automatically enables first-party mode (bundle + proxy). See below to customise.
useScriptVimeoPlayer()
The useScriptVimeoPlayer composable lets you have fine-grain control over when and how Vimeo Player is loaded on your site.
const { proxy } = useScriptVimeoPlayer()
const { Vimeo } = await proxyPlease follow the Registry Scripts guide to learn more about advanced usage.
First-Party Mode: Privacy Focused Proxy
No extra config needed. The script is bundled from your domain (faster loads, no extra DNS lookup) and runtime requests are reverse-proxied through your server with automatic anonymisation (user IPs stay hidden from Vimeo Player, works with ad blockers). Learn more.
export default defineNuxtConfig({
scripts: {
// ✅ First-party mode: bundled + proxied
registry: {
vimeoPlayer: {
trigger: 'onNuxtReady',
},
},
},
})Example
Using Vimeo Player in a component with the proxy to send events .
<script setup lang="ts">
const { proxy } = useScriptVimeoPlayer()
// noop in development, ssr
// just works in production, client
function handleAction() {
const { Vimeo } = await proxy
}
</script>
<template>
<div>
<button @click="handleAction">
Send Event
</button>
</div>
</template>Types
Install @vimeo/player, which includes its own types, for full TypeScript support.
pnpm add -D @vimeo/player
<ScriptVimeoPlayer>
<ScriptVimeoPlayer> wraps useScriptVimeoPlayer() with a lazy placeholder and headless player UI.
An Element Event Trigger delays the Vimeo player until the configured event fires.
The default event is mousedown.
The player accepts either id or url, but the current oEmbed thumbnail request reads only id. When you pass only url, provide your own #placeholder content or also pass the numeric video ID.
Demo
Eager Loading Placeholder
The Vimeo video placeholder is lazy-loaded by default. For an above-the-fold video, load the image eagerly or replace it through the #placeholder slot.
<ScriptVimeoPlayer above-the-fold />
Component API
See the Facade Component API for full props, events, and slots.
Events
The component forwards the Vimeo Player SDK events below. See Player Events for payload details. A failure while loading the SDK also emits error, but without the event and player arguments declared for Vimeo's own error event.
const emits = defineEmits<{
play: [e: EventMap['play'], player: Player]
playing: [e: EventMap['playing'], player: Player]
pause: [e: EventMap['pause'], player: Player]
ended: [e: EventMap['ended'], player: Player]
timeupdate: [e: EventMap['timeupdate'], player: Player]
progress: [e: EventMap['progress'], player: Player]
seeking: [e: EventMap['seeking'], player: Player]
seeked: [e: EventMap['seeked'], player: Player]
texttrackchange: [e: EventMap['texttrackchange'], player: Player]
chapterchange: [e: EventMap['chapterchange'], player: Player]
cuechange: [e: EventMap['cuechange'], player: Player]
cuepoint: [e: EventMap['cuepoint'], player: Player]
volumechange: [e: EventMap['volumechange'], player: Player]
playbackratechange: [e: EventMap['playbackratechange'], player: Player]
bufferstart: [e: EventMap['bufferstart'], player: Player]
bufferend: [e: EventMap['bufferend'], player: Player]
error: [e: EventMap['error'], player: Player]
loaded: [e: EventMap['loaded'], player: Player]
durationchange: [e: EventMap['durationchange'], player: Player]
fullscreenchange: [e: EventMap['fullscreenchange'], player: Player]
qualitychange: [e: EventMap['qualitychange'], player: Player]
camerachange: [e: EventMap['camerachange'], player: Player]
resize: [e: EventMap['resize'], player: Player]
enterpictureinpicture: [e: EventMap['enterpictureinpicture'], player: Player]
leavepictureinpicture: [e: EventMap['leavepictureinpicture'], player: Player]
}>()
Slots
Use the slots to control the facade around the player.
default
Always visible.
<template>
<ScriptVimeoPlayer :id="331567154">
<div class="bg-blue-500 text-white p-5">
Video by NuxtJS
</div>
</ScriptVimeoPlayer>
</template>
awaitingLoad
Shown while the component waits for its element trigger.
<template>
<ScriptVimeoPlayer :id="331567154">
<template #awaitingLoad>
<div class="bg-blue-500 text-white p-5">
Click to play!
</div>
</template>
</ScriptVimeoPlayer>
</template>
loading
Shown while the Vimeo SDK loads.
<template>
<ScriptVimeoPlayer :id="331567154">
<template #loading>
<div class="bg-blue-500 text-white p-5">
Loading...
</div>
</template>
</ScriptVimeoPlayer>
</template>
placeholder
Replaces the default Vimeo thumbnail. The slot receives the resolved placeholder URL.
<template>
<ScriptVimeoPlayer :id="331567154">
<template #placeholder="{ placeholder }">
<img :src="placeholder" alt="Video Placeholder">
</template>
</ScriptVimeoPlayer>
</template>
useScriptVimeoPlayer()
Use useScriptVimeoPlayer() when you need to load the Vimeo Player SDK and create a player programmatically.
export function useScriptVimeoPlayer<T extends VimeoPlayerApi>(_options?: VimeoPlayerInput) {}
For triggers, proxying, and other script options, see Registry Scripts.
type Constructor<T extends new (...args: any) => any> = T extends new (...args: infer A) => infer R ? new (...args: A) => R : neverExample
Loading the Vimeo Player SDK and interacting with it programmatically.
<script setup lang="ts">
const video = ref()
const { onLoaded } = useScriptVimeoPlayer()
let player
onLoaded(({ Vimeo }) => {
player = new Vimeo.Player(video.value, {
id: 331567154
})
})
function play() {
player?.play()
}
</script>
<template>
<div>
<div ref="video" />
<button @click="play">
Play
</button>
</div>
</template>