Vimeo Player API

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

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's required to load the script dynamically via the RequireJS load system. http://www.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>

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 IE 11+, Chrome, Firefox, Safari, and Opera.

Migrate from Froogaloop

Using our old Froogaloop library? See the migration doc for details on how to update your code to use this library.

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>

Create a Player
Embed Options
Methods
Events

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 `<iframe>`’s id
// Assumes that there is an <iframe id="player1"> on the page.
const idPlayer = new Vimeo.Player('player1');

Create an embed

Pass any element and an options object to the Vimeo.Player constructor to make an embed inside that element. The options object should consist of either an id or url and any other embed options for the embed.

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

    // Will create inside the made-in-ny div:
    // <iframe src="https://player.vimeo.com/video/59777392?h=ab882a04fd&loop=1" width="640" height="360" frameborder="0" allowfullscreen allow="autoplay; encrypted-media"></iframe>
    const madeInNy = new Vimeo.Player('made-in-ny', options);
</script>

Embed options will also be read from the data-vimeo-* attributes. Attributes on the element will override any defined in the options object passed to the constructor (similar to how the style attribute overrides styles defined in CSS).

Elements with a data-vimeo-id or data-vimeo-url attribute will have embeds created automatically when the player API library is loaded. You can use the data-vimeo-defer attribute to prevent that from happening and create the embed at a later time. This is useful for situations where the player embed wouldn’t be visible right away, but only after some action was taken by the user (a lightbox opened from clicking on a thumbnail, for example).

<div data-vimeo-id="59777392" data-vimeo-defer id="made-in-ny"></div>
<div data-vimeo-id="19231868" data-vimeo-defer data-vimeo-width="500" id="handstick"></div>

<script src="https://player.vimeo.com/api/player.js"></script>
<script>
    const options = {
        width: 640,
        loop: true
    };

    // Will create inside the made-in-ny div:
    // <iframe src="https://player.vimeo.com/video/59777392?h=ab882a04fd&loop=1" width="640" height="360" frameborder="0" allowfullscreen allow="autoplay; encrypted-media"></iframe>
    const madeInNy = new Vimeo.Player('made-in-ny', options);

    // Will create inside the handstick div:
    // <iframe src="https://player.vimeo.com/video/19231868?h=1034d5269b&loop=1" width="500" height="281" frameborder="0" allowfullscreen allow="autoplay; encrypted-media"></iframe>
    const handstick = new Vimeo.Player(document.getElementById('handstick'), options);
</script>

Embed Options

These options are available to be appended to the query string of the player URL, used as data-vimeo- attributes on elements, or included as an object passed to the Vimeo.Player constructor. The complete list of embed options can be found in our official SDK documentation.

Methods

You can call methods on the player by calling the function on the Player object:

player.play();

All methods, except for on() and off() return a Promise. The Promise may or may not resolve with a value, depending on the specific method.

player.disableTextTrack().then(function() {
    // the track was disabled
}).catch(function(error) {
    // an error occurred
});

Promises for getters are resolved with the value of the property:

player.getLoop().then(function(loop) {
    // whether or not the player is set to loop
});

Promises for setters are resolved with the value set, or rejected with an error if the set fails. For example:

player.setColor('#00adef').then(function(color) {
    // the color that was set
}).catch(function(error) {
    // an error occurred setting the color
});

on(event: string, callback: function): void

Add an event listener for the specified event. Will call the callback with a single parameter, data, that contains the data for that event. See events below for