The Vimeo Player API allows you to interact with and control an embedded Vimeo Player.

Note

We'd love to get your feedback about how you work with Player.js. Please take a few minutes to share your thoughts in our survey here.

Installation

You can install the Vimeo Player API through either npm:

npm install @vimeo/player

Alternatively, you can reference an up‐to‐date version on our CDN:

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

Warning: when used with RequireJS it is required to load the script dynamically via the RequireJS load system. https://requirejs.org/docs/api.html#jsfiles

Getting Started

In order to control the Vimeo Player, you need a player to control. There are a few ways to get a player:

Pre-existing player

Already have a player on the page? Pass the element to the Vimeo.Player constructor and you’re ready to go.

<iframe src="https://player.vimeo.com/video/76979871?h=8272103f6e" width="640" height="360" frameborder="0" allowfullscreen allow="autoplay; encrypted-media"></iframe>
<script src="https://player.vimeo.com/api/player.js"></script>
<script>
    const iframe = document.querySelector('iframe');
    const player = new Vimeo.Player(iframe);
    player.on('play', function() {
        console.log('played the video!');
    });
    player.getVideoTitle().then(function(title) {
        console.log('title:', title);
    });
</script>

Create with a video id or url

You can use the library to make the embed for you. All you need is an empty element and the video id or vimeo.com url (and optional embed options).

Note

If the video privacy settings are "Unlisted", instead of providing an id property, you will need to provide the full video URL as a url property and include the h parameter.

<div id="made-in-ny"></div>
<script src="https://player.vimeo.com/api/player.js"></script>
<script>
    const options = {
        id: 59777392,
        width: 640,
        loop: true
    };
    const player = new Vimeo.Player('made-in-ny', options);
    player.setVolume(0);
    player.on('play', function() {
        console.log('played the video!');
    });
</script>

Important

Embed options will only be used when creating a new embed, not when attaching to an existing iframe.

Automatically with HTML attributes

When the library loads, it will scan your page for elements with Vimeo attributes. Each element must have at least a data-vimeo-id or data-vimeo-url attribute in order for the embed to be created automatically. You can also add attributes for any of the embed options, prefixed with data-vimeo (data-vimeo-portrait="false", for example).

Note

If the video privacy settings are "Unlisted", instead of providing a data-vimeo-id attribute, you will need to provide the full video URL in a data-vimeo-url attribute and include the h parameter.

<div data-vimeo-id="19231868" data-vimeo-width="640" id="handstick"></div>
<div data-vimeo-url="https://player.vimeo.com/video/76979871?h=8272103f6e" id="playertwo"></div>
<script src="https://player.vimeo.com/api/player.js"></script>
<script>
    // If you want to control the embeds, you’ll need to create a Player object.
    // You can pass either the `<div>` or the `<iframe>` created inside the div.
    const handstickPlayer = new Vimeo.Player('handstick');
    handstickPlayer.on('play', function() {
        console.log('played the handstick video!');
    });
    const playerTwoPlayer = new Vimeo.Player('playertwo');
    playerTwoPlayer.on('play', function() {
        console.log('played the player 2.0 video!');
    });
</script>

Browser Support

The Player API library is supported in the last two versions of Edge, Firefox, Safari, Opera, and Chrome (incl. Chromium based browsers).

Using with a module bundler

If you’re using a module bundler like webpack or rollup, the exported object will be the Player constructor (unlike the browser where it is attached to window.Vimeo):

import Player from '@vimeo/player';
const player = new Player('handstick', {
    id: 19231868,
    width: 640
});
player.on('play', function() {
    console.log('played the video!');
});

Similarly, if you’re using RequireJS in the browser, it will also import the Player constructor directly:

<iframe src="https://player.vimeo.com/video/76979871?h=8272103f6e" width="640" height="360" frameborder="0" allowfullscreen allow="autoplay; encrypted-media"></iframe>
<script>
    require(['https://player.vimeo.com/api/player.js'], function (Player) {
        const iframe = document.querySelector('iframe');
        const player = new Player(iframe);
        player.on('play', function() {
            console.log('played the video!');
        });
    });
</script>

Table of Contents generated with DocToc

Create a Player

The Vimeo.Player object wraps an iframe so you can interact with and control a Vimeo Player embed.

Existing embed

If you already have a Vimeo <iframe> on your page, pass that element into the constructor to get a Player object. You can also use jQuery to select the element, or pass a string that matches the id of the <iframe>.

"// Select with the DOM API const iframe = document.querySelector('iframe'); const iframePlayer = new Vimeo.Player(iframe); // Select with jQuery // If multiple elements are selected, it will use the first element. const jqueryPlayer = new Vimeo.Player($('iframe')); // Select with the `