Registry / web-framework / vimeo-video-element

vimeo-video-element

library1.7.1jsnpmunverified

vimeo-video-element is a custom web component that encapsulates the Vimeo player, providing a JavaScript API that closely mirrors the standard HTML `HTMLMediaElement` interface. It is part of the `media-elements` monorepo by Mux and is currently at version 1.7.1, with recent updates focused on bug fixes and dependency management. The project maintains an active development pace with frequent minor releases. Key differentiators include its adherence to the native `<video>` API for familiar usage, seamless integration with `Media Chrome` components for UI, and its nature as a custom element, allowing for easy drop-in usage in various web frameworks or vanilla JavaScript. It ships with TypeScript types, enhancing developer experience and type safety.

web-framework

npm install vimeo-video-element

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VIMEO-VIDEO-ELEMEN

vimeo-video-element

web-frameworkjavascriptv1.7.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

vimeo-video-element

✓ import 'vimeo-video-element';

✗ const VimeoVideoElement = require('vimeo-video-element');

This is the primary way to register the custom element globally in the browser. It typically doesn't export a class for direct instantiation, as web components are primarily used declaratively in HTML. CommonJS `require` is not supported for browser-side custom element registration.

VimeoVideoElement (Class)

✓ import { VimeoVideoElement } from 'vimeo-video-element';

✗ import VimeoVideoElement from 'vimeo-video-element';

While the primary use is a side-effect import, if you need to extend or programmatically instantiate the class, it is typically exported as a named export. This allows for advanced customization or integration with frameworks that prefer class-based instantiation.

Type definitions

✓ import type { VimeoVideoElement } from 'vimeo-video-element';

The package ships with TypeScript types. Use `import type` for type-only imports to ensure they are stripped during transpilation, avoiding runtime overhead.

This quickstart demonstrates how to embed and interact with the `<vimeo-video>` custom element using basic HTML and JavaScript, including attributes for playback control and accessing the underlying Vimeo player API.

<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Vimeo Video Element Quickstart</title> <style> vimeo-video { display: block; width: 100%; max-width: 640px; aspect-ratio: 16 / 9; margin: 20px auto; border: 1px solid #ccc; box-shadow: 0 4px 8px rgba(0,0,0,0.1); } </style> <script type="module" src="https://cdn.jsdelivr.net/npm/vimeo-video-element@latest/+esm"></script> </head> <body> <h1>Vimeo Video Element Example</h1> <vimeo-video controls autoplay muted src="https://vimeo.com/648359100" data-poster="https://i.vimeocdn.com/video/1351111111_640.webp" ></vimeo-video> <vimeo-video src="https://vimeo.com/76979871?h=8272103f6e" playsinline loop controls ></vimeo-video> <script type="module"> const videoElement = document.querySelector('vimeo-video'); videoElement.addEventListener('play', () => { console.log('Video started playing!'); }); // You can access the underlying player API if needed videoElement.ready.then((player) => { player.getDuration().then((duration) => { console.log('Video duration:', duration, 'seconds'); }); }); </script> </body> </html>

Debug

Known issues

gotchaWhen using the `src` attribute, ensure the Vimeo URL is a direct video link (e.g., `https://vimeo.com/VIDEO_ID`). Using manage, showcase, or account URLs will not work as expected. For unlisted videos, the `h` parameter must be included in the URL.

fix

Always use the standard shareable Vimeo video URL. For unlisted videos, obtain the URL including the hash parameter from Vimeo's share options. Example: `https://vimeo.com/123456789?h=abcdef123`.

affects: >=1.0.0

gotchaVimeo's embed privacy settings can prevent videos from playing. Videos set to 'Specific Domains' will only play if the embedding domain is whitelisted on Vimeo. 'Private' videos will generally not render; they must be 'Public' or 'Unlisted'.

fix

Configure Vimeo video privacy settings to 'Public', 'Unlisted', or explicitly whitelist your domain(s) for 'Specific Domains' embedding. Consult Vimeo's embed settings for details.

affects: >=1.0.0

gotchaAutoplay behavior can be inconsistent across browsers due to policies designed to prevent unwanted media playback. Many browsers require videos to be muted or user-interacted before autoplaying.

fix

Always include the `muted` attribute when attempting autoplay (`<vimeo-video autoplay muted ...>`). Consider providing a UI element for users to initiate playback if autoplay is critical.

affects: >=1.0.0

gotchaThe `<vimeo-video>` element mimics the `HTMLMediaElement` API, but not all properties or methods may be fully supported or behave identically to a native `<video>` tag, especially for advanced features like `preload` or specific track manipulations.

fix

Refer to the `vimeo-video-element` documentation for supported properties and methods. For advanced interactions or behavior differing from native `<video>`, utilize the `player` object accessible via the `ready` promise for direct Vimeo player API access.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Failed to execute 'define' on 'CustomElementRegistry': the name 'vimeo-video' has already been used

The `<vimeo-video>` custom element script was imported or executed multiple times, attempting to define the same element name more than once.

fix

Ensure the `vimeo-video-element` script (or its containing bundle) is imported only once in your application. If using a CDN script, place it strategically to avoid re-execution.

The custom element '<vimeo-video>' has not been defined.

The `<vimeo-video>` custom element was used in HTML before its definition script (`import 'vimeo-video-element';`) had been loaded and executed by the browser.

fix

Make sure the JavaScript import or `<script type="module">` tag for `vimeo-video-element` is placed either at the end of `<body>` or marked as `defer` in the `<head>` to ensure the element is defined before the browser attempts to parse and render it. For CDN usage, use `<script type="module" src="..."></script>`.

Vimeo Error: This video can't be embedded because it belongs to a private channel or is too restricted. (Error code: 1000)

The video specified in the `src` attribute has privacy settings on Vimeo that prevent it from being embedded on the current domain or publicly.

fix

Review the video's privacy settings on Vimeo. Ensure embedding is allowed, either globally, for specific domains (if yours is whitelisted), or that the video is set to 'Unlisted' or 'Public'.

Upgrade

Version history

1.7.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/muxinc/media-elements ↗

packagehttps://www.npmjs.com/package/vimeo-video-element ↗

homepagehttps://www.media-chrome.org/ ↗