Comprehensive Guide to Embedding Vimeo Videos for Developers

22. March 2025

.SHARE

Embedding Vimeo videos on your website provides a seamless viewing experience for your visitors without requiring them to navigate away to Vimeo’s platform. This guide explores various methods for embedding Vimeo videos, with a focus on programmer-friendly solutions that offer customization and control.

Basic Embedding Options

Standard iframe Embed

The simplest way to embed a Vimeo video is by using the iframe embed code that Vimeo provides:


<iframe 
  src="https://player.vimeo.com/video/VIDEO_ID?h=HASH_ID" 
  width="640" 
  height="360" 
  frameborder="0" 
  allowfullscreen 
  allow="autoplay; encrypted-media">
</iframe>

<iframe

src="https://player.vimeo.com/video/VIDEO_ID?h=HASH_ID"

width="640"

height="360"

frameborder="0"

allowfullscreen

allow="autoplay; encrypted-media">

</iframe>

Replace VIDEO_ID with your Vimeo video ID. If your video is unlisted, you’ll need to include the h=HASH_ID parameter in the URL.

HTML5 Attributes for Automatic Embedding

You can also use HTML5 data attributes to let the Vimeo Player API automatically create embeds:


<div 
  data-vimeo-id="VIDEO_ID" 
  data-vimeo-width="640">
</div>

<script src="https://player.vimeo.com/api/player.js"></script>

<div

data-vimeo-id="VIDEO_ID"

data-vimeo-width="640">

</div>

The Player API will scan your page for elements with data-vimeo attributes and create embeds automatically. You can add various parameters using additional data attributes:


<div 
  data-vimeo-id="59777392" 
  data-vimeo-width="640" 
  data-vimeo-loop="true" 
  data-vimeo-color="ffffff">
</div>

<div

data-vimeo-id="59777392"

data-vimeo-width="640"

data-vimeo-loop="true"

data-vimeo-color="ffffff">

</div>

oEmbed Implementation

oEmbed is an open format that allows embedded content from one site to be displayed on another site. Vimeo supports oEmbed, making it a reliable way to programmatically retrieve embed codes and video metadata.

Using the oEmbed Endpoint


// Example using fetch
fetch('https://vimeo.com/api/oembed.json?url=https://vimeo.com/VIDEO_ID')
  .then(response => response.json())
  .then(data => {
    // data.html contains the embed code
    document.getElementById('vimeo-container').innerHTML = data.html;
    
    // data also contains useful metadata
    console.log('Video title:', data.title);
    console.log('Author name:', data.author_name);
    console.log('Thumbnail URL:', data.thumbnail_url);
  })
  .catch(error => console.error('Error fetching oEmbed data:', error));

// Example using fetch

fetch('https://vimeo.com/api/oembed.json?url=https://vimeo.com/VIDEO_ID')

.then(response => response.json())

.then(data => {

// data.html contains the embed code

document.getElementById('vimeo-container').innerHTML = data.html;

// data also contains useful metadata

console.log('Video title:', data.title);

console.log('Author name:', data.author_name);

console.log('Thumbnail URL:', data.thumbnail_url);

})

.catch(error => console.error('Error fetching oEmbed data:', error));

oEmbed Parameters

You can customize the embed by adding parameters to the oEmbed URL:


const url = 'https://vimeo.com/api/oembed.json?url=https://vimeo.com/VIDEO_ID'
  + '&width=640'
  + '&height=360'
  + '&autoplay=1'
  + '&loop=1'
  + '&color=ffffff';

const url = 'https://vimeo.com/api/oembed.json?url=https://vimeo.com/VIDEO_ID'

+ '&width=640'

+ '&height=360'

+ '&autoplay=1'

+ '&loop=1'

+ '&color=ffffff';

Common oEmbed parameters include:

width and height: Dimensions in pixels
autoplay: Set to 1 to auto-play the video
loop: Set to 1 to loop the video
color: Player color in hex format (without the #)
portrait: Set to 0 to hide the user’s portrait
title: Set to 0 to hide the title
byline: Set to 0 to hide the byline

Vimeo Player SDK

The Vimeo Player SDK gives you programmatic control over embedded Vimeo players. This JavaScript library allows you to interact with the player, listen for events, and control playback.

Installation

You can install the Player SDK via npm:


npm install @vimeo/player

npm install @vimeo/player

Alternatively, include it directly from Vimeo’s CDN:


<script src="https://player.vimeo.com/api/player.js"></script>

Creating a Player Instance


// From an existing iframe
const iframe = document.querySelector('iframe');
const player = new Vimeo.Player(iframe);

// Or create a new embed
const options = {
  id: 59777392,
  width: 640,
  loop: true
};

const player = new Vimeo.Player('container-element', options);

// From an existing iframe

const iframe = document.querySelector('iframe');

const player = new Vimeo.Player(iframe);

// Or create a new embed

const options = {

id: 59777392,

width: 640,

loop: true

};

const player = new Vimeo.Player('container-element', options);

Event Handling

Listen for player events:


player.on('play', function() {
  console.log('Video started playing');
});

player.on('pause', function() {
  console.log('Video paused');
});

player.on('ended', function() {
  console.log('Video ended');
});

player.on('timeupdate', function(data) {
  console.log('Current playback position:', data.seconds);
  console.log('Percentage watched:', data.percent);
});

player.on('play', function() {

console.log('Video started playing');

});

player.on('pause', function() {

console.log('Video paused');

});

player.on('ended', function() {

console.log('Video ended');

});

player.on('timeupdate', function(data) {

console.log('Current playback position:', data.seconds);

console.log('Percentage watched:', data.percent);

});

Controlling the Player


// Play the video
player.play().then(function() {
  // The video is playing
}).catch(function(error) {
  // Error occurred
});

// Pause the video
player.pause();

// Seek to a specific time (in seconds)
player.setCurrentTime(30.5);

// Change the volume (0 to 1)
player.setVolume(0.5);

// Load a different video
player.loadVideo(76979871);

// Play the video

player.play().then(function() {

// The video is playing

}).catch(function(error) {

// Error occurred

});

// Pause the video

player.pause();

// Seek to a specific time (in seconds)

player.setCurrentTime(30.5);

// Change the volume (0 to 1)

player.setVolume(0.5);

// Load a different video

player.loadVideo(76979871);

Advanced SDK Methods


// Get the current playback position
player.getCurrentTime().then(function(seconds) {
  console.log('Current time:', seconds);
});

// Get the video duration
player.getDuration().then(function(duration) {
  console.log('Video duration:', duration);
});

// Check if the video is paused
player.getPaused().then(function(paused) {
  if (paused) {
    console.log('Video is paused');
  } else {
    console.log('Video is playing');
  }
});

// Toggle fullscreen
player.requestFullscreen();
player.exitFullscreen();

// Enable or disable captions/subtitles
player.enableTextTrack('en').then(function(track) {
  console.log('Track enabled:', track.language, track.kind);
});
player.disableTextTrack();

// Get the current playback position

player.getCurrentTime().then(function(seconds) {

console.log('Current time:', seconds);

});

// Get the video duration

player.getDuration().then(function(duration) {

console.log('Video duration:', duration);

});

// Check if the video is paused

player.getPaused().then(function(paused) {

if (paused) {

console.log('Video is paused');

} else {

console.log('Video is playing');

}

});

// Toggle fullscreen

player.requestFullscreen();

player.exitFullscreen();

// Enable or disable captions/subtitles

player.enableTextTrack('en').then(function(track) {

console.log('Track enabled:', track.language, track.kind);

});

player.disableTextTrack();

Advanced Customization Options

Player Parameters

You can customize the Vimeo player appearance and behavior using URL parameters:


<iframe 
  src="https://player.vimeo.com/video/VIDEO_ID?h=HASH_ID&color=ffffff&title=0&byline=0&portrait=0&controls=0" 
  width="640" 
  height="360" 
  frameborder="0" 
  allowfullscreen 
  allow="autoplay; encrypted-media">
</iframe>

<iframe

src="https://player.vimeo.com/video/VIDEO_ID?h=HASH_ID&color=ffffff&title=0&byline=0&portrait=0&controls=0"

width="640"

height="360"

frameborder="0"

allowfullscreen

allow="autoplay; encrypted-media">

</iframe>

Common URL parameters:

color: Player color in hex format (without the #)
title=0: Hide the title
byline=0: Hide the byline
portrait=0: Hide the user’s portrait
controls=0: Hide player controls
autoplay=1: Auto-play the video
loop=1: Loop the video
muted=1: Mute the video (useful for autoplay)
background=1: Enable background mode (no controls, looping, muted)

Custom Player Styling with CSS

You can further customize the appearance of the embedded player with CSS:


/* Remove the iframe border */
iframe {
  border: none;
}

/* Create a responsive container for the iframe */
.video-container {
  position: relative;
  padding-bottom: 56.25%; /* 16:9 aspect ratio */
  height: 0;
  overflow: hidden;
  max-width: 100%;
}

.video-container iframe {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
}

/* Remove the iframe border */

iframe {

border: none;

}

/* Create a responsive container for the iframe */

.video-container {

position: relative;

padding-bottom: 56.25%; /* 16:9 aspect ratio */

height: 0;

overflow: hidden;

max-width: 100%;

}

.video-container iframe {

position: absolute;

top: 0;

left: 0;

width: 100%;

height: 100%;

}

Working with Private or Hidden Videos

Unlisted Videos

For unlisted videos, you need to include the hash parameter in the URL:


<iframe src="https://player.vimeo.com/video/VIDEO_ID?h=HASH_ID" width="640" height="360" frameborder="0" allowfullscreen></iframe>

When using the Player SDK:


const options = {
  url: 'https://player.vimeo.com/video/VIDEO_ID?h=HASH_ID'
};

const player = new Vimeo.Player('container-element', options);

const options = {

url: 'https://player.vimeo.com/video/VIDEO_ID?h=HASH_ID'

};

const player = new Vimeo.Player('container-element', options);

Private Videos

For private videos, you’ll need to authenticate users or use unlisted videos with a hash parameter. The oEmbed endpoint can be used with appropriate parameters:


// For private videos that require a token
fetch('https://vimeo.com/api/oembed.json?url=https://vimeo.com/VIDEO_ID/HASH_TOKEN')
  .then(response => response.json())
  .then(data => {
    document.getElementById('vimeo-container').innerHTML = data.html;
  });

// For private videos that require a token

fetch('https://vimeo.com/api/oembed.json?url=https://vimeo.com/VIDEO_ID/HASH_TOKEN')

.then(response => response.json())

.then(data => {

document.getElementById('vimeo-container').innerHTML = data.html;

});

Responsive Embedding Techniques

CSS-Based Responsive Embeds

To make Vimeo embeds responsive:


.video-wrapper {
  position: relative;
  padding-bottom: 56.25%; /* 16:9 aspect ratio */
  height: 0;
  overflow: hidden;
}

.video-wrapper iframe {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
}

.video-wrapper {

position: relative;

padding-bottom: 56.25%; /* 16:9 aspect ratio */

height: 0;

overflow: hidden;

}

.video-wrapper iframe {

position: absolute;

top: 0;

left: 0;

width: 100%;

height: 100%;

}


<div class="video-wrapper">
  <iframe src="https://player.vimeo.com/video/VIDEO_ID" frameborder="0" allowfullscreen></iframe>
</div>

</div>

JavaScript Responsive Solution

For more complex responsive behaviors:


function resizeVimeoPlayer() {
  const container = document.querySelector('.video-container');
  const containerWidth = container.offsetWidth;
  
  // Maintain 16:9 aspect ratio
  const height = containerWidth * 0.5625;
  
  player.element.style.width = containerWidth + 'px';
  player.element.style.height = height + 'px';
}

// Resize on page load
window.addEventListener('load', resizeVimeoPlayer);

// Resize on window resize
window.addEventListener('resize', resizeVimeoPlayer);

function resizeVimeoPlayer() {

const container = document.querySelector('.video-container');

const containerWidth = container.offsetWidth;

// Maintain 16:9 aspect ratio

const height = containerWidth * 0.5625;

player.element.style.width = containerWidth + 'px';

player.element.style.height = height + 'px';

}

// Resize on page load

window.addEventListener('load', resizeVimeoPlayer);

// Resize on window resize

window.addEventListener('resize', resizeVimeoPlayer);

Performance Optimization

Lazy Loading Videos

Improve page load performance by loading videos only when they come into view:


<div class="video-container" data-vimeo-id="VIDEO_ID" id="vimeo-container"></div>

<script>
  const observerOptions = {
    root: null,
    rootMargin: '0px',
    threshold: 0.1
  };
  
  const observer = new IntersectionObserver((entries, observer) => {
    entries.forEach(entry => {
      if (entry.isIntersecting) {
        const container = entry.target;
        const videoId = container.dataset.vimeoId;
        
        const player = new Vimeo.Player(container, {
          id: videoId,
          width: container.offsetWidth
        });
        
        // Stop observing after loading
        observer.unobserve(container);
      }
    });
  }, observerOptions);
  
  // Start observing
  observer.observe(document.getElementById('vimeo-container'));
</script>

const observerOptions = {

root: null,

rootMargin: '0px',

threshold: 0.1

};

const observer = new IntersectionObserver((entries, observer) => {

entries.forEach(entry => {

if (entry.isIntersecting) {

const container = entry.target;

const videoId = container.dataset.vimeoId;

const player = new Vimeo.Player(container, {

id: videoId,

width: container.offsetWidth

});

// Stop observing after loading

observer.unobserve(container);

}

});

}, observerOptions);

// Start observing

observer.observe(document.getElementById('vimeo-container'));

</script>

Deferring Script Loading

Improve page load performance by deferring the Player SDK loading:


<script defer src="https://player.vimeo.com/api/player.js"></script>

Or load it dynamically:


function loadVimeoPlayerAPI() {
  const script = document.createElement('script');
  script.src = 'https://player.vimeo.com/api/player.js';
  script.onload = initializeVimeoPlayers;
  document.body.appendChild(script);
}

function initializeVimeoPlayers() {
  // Initialize your players here
  const player = new Vimeo.Player('container-element', {
    id: 59777392
  });
}

// Load when needed
document.getElementById('load-video-button').addEventListener('click', loadVimeoPlayerAPI);

function loadVimeoPlayerAPI() {

const script = document.createElement('script');

script.src = 'https://player.vimeo.com/api/player.js';

script.onload = initializeVimeoPlayers;

document.body.appendChild(script);

}

function initializeVimeoPlayers() {

// Initialize your players here

const player = new Vimeo.Player('container-element', {

id: 59777392

});

}

// Load when needed

document.getElementById('load-video-button').addEventListener('click', loadVimeoPlayerAPI);

Troubleshooting Common Issues

Cross-Origin Issues

Ensure you have the appropriate CORS headers if making API requests from your domain.

Autoplay Restrictions

Modern browsers restrict autoplay with sound. To work around this:


// Always mute when using autoplay
const player = new Vimeo.Player('container-element', {
  id: 59777392,
  autoplay: true,
  muted: true
});

// Or check if autoplay is allowed before playing
player.ready().then(() => {
  player.play().catch((error) => {
    console.log('Autoplay was prevented. Muting and trying again.');
    player.setVolume(0).then(() => player.play());
  });
});

// Always mute when using autoplay

const player = new Vimeo.Player('container-element', {

id: 59777392,

autoplay: true,

muted: true

});

// Or check if autoplay is allowed before playing

player.ready().then(() => {

player.play().catch((error) => {

console.log('Autoplay was prevented. Muting and trying again.');

player.setVolume(0).then(() => player.play());

});

Mobile Playback Issues

For better mobile compatibility:


<iframe 
  src="https://player.vimeo.com/video/VIDEO_ID?playsinline=1" 
  width="640" 
  height="360" 
  frameborder="0" 
  allowfullscreen 
  allow="autoplay; encrypted-media; picture-in-picture; fullscreen; playsinline">
</iframe>

<iframe

src="https://player.vimeo.com/video/VIDEO_ID?playsinline=1"

width="640"

height="360"

frameborder="0"

allowfullscreen

allow="autoplay; encrypted-media; picture-in-picture; fullscreen; playsinline">

</iframe>

The playsinline parameter and allow="playsinline" attribute help with iOS playback.

Thoughts

Vimeo offers multiple embedding options for developers, from simple iframe embeds to powerful SDK controls. By using the techniques outlined in this guide, you can create customized, responsive, and performant video experiences on your website.

For the most up-to-date documentation, always refer to Vimeo’s official developer resources:

Let’s Talk!

Looking for a reliable partner to bring your project to the next level? Whether it’s development, design, security, or ongoing support—I’d love to chat and see how I can help.

Get in touch,
and let’s create something amazing together!

Day 28: FrankenWP – FrankePHP + WordPress – 7 Days of Docker

Development / Deployment / Docker / Hosting / WordPress

FrankenWP is a specialized WordPress Docker image built on FrankenPHP, which is a PHP application server built on top of the Caddy web server. This combination offers several advantages: This guide will walk you through setting up FrankenWP on your own server using Docker Compose, including all necessary configuration options and client connection details. Also […]

FrankenPHP in 2025: The Zombie App Server That Brought PHP Back From the Dead!

Development / Automation / Build-Tools / Debugging / Deployment / Enviroment / Local / PHP

Remember when people used to joke that PHP was dying? Well, in 2025, PHP is not only alive and kicking but thriving thanks to its Frankenstein-inspired application server that’s been taking the web development world by storm! What Is This Monster? FrankenPHP is the brainchild of Kévin Dunglas (the same genius behind API Platform) who […]

The Ultimate Guide to Presence Detection in JavaScript: What Works and Why

Development / API / Javascript

Hey there! Ever wondered how websites know when you’re actually looking at them, or if you’ve wandered off to make coffee? That’s presence detection in action – and it’s super useful for creating responsive, user-friendly web apps. In this guide, I’ll walk you through everything you need to know about detecting user presence with JavaScript […]

Alexander

I am a full-stack developer. My expertise include:

Server, Network and Hosting Environments
Data Modeling / Import / Export
Business Logic
API Layer / Action layer / MVC
User Interfaces
User Experience
Understand what the customer and the business needs

I have a deep passion for programming, design, and server architecture—each of these fuels my creativity, and I wouldn’t feel complete without them.

With a broad range of interests, I’m always exploring new technologies and expanding my knowledge wherever needed. The tech world evolves rapidly, and I love staying ahead by embracing the latest innovations.

Beyond technology, I value peace and surround myself with like-minded individuals.

I firmly believe in the principle: Help others, and help will find its way back to you when you need it.

Comprehensive Guide to Embedding Vimeo Videos for Developers

Table of Contents

Basic Embedding Options

Standard iframe Embed

HTML5 Attributes for Automatic Embedding

oEmbed Implementation

Using the oEmbed Endpoint

oEmbed Parameters

Vimeo Player SDK

Installation

Creating a Player Instance

Event Handling

Controlling the Player

Advanced SDK Methods

Advanced Customization Options

Player Parameters

Custom Player Styling with CSS

Working with Private or Hidden Videos

Unlisted Videos

Private Videos

Responsive Embedding Techniques

CSS-Based Responsive Embeds

JavaScript Responsive Solution

Performance Optimization

Lazy Loading Videos

Deferring Script Loading

Troubleshooting Common Issues

Cross-Origin Issues

Autoplay Restrictions

Mobile Playback Issues

Thoughts

RELATED POSTS

Day 28: FrankenWP – FrankePHP + WordPress – 7 Days of Docker

FrankenPHP in 2025: The Zombie App Server That Brought PHP Back From the Dead!

The Ultimate Guide to Presence Detection in JavaScript: What Works and Why

Alexander

DISCOVER.

.highlights

.highlights