Skip to content
Astro Embed

Vimeo

The <Vimeo> component generates an embed using a lightweight custom element that will load Vimeo’s <iframe> only when a user clicks play.

Vimeo embeds will always require some JavaScript, but this is one of the most minimal and performant ways to embed a Vimeo video.

Usage

---
import { Vimeo } from 'astro-embed';
---


<Vimeo id="32001208" />

You can also pass in the full URL for the video:

<Vimeo id="https://vimeo.com/32001208" />

The above code produces the following result:

Optional props

In addition to the required id prop, the following props are available to customise how the <Vimeo> component renders:

poster

Type: string

You can provide an alternative poster image by passing in a URL to the poster prop.

For example, this is the same video as above but with a custom poster image:

<Vimeo
  id="32001208"
  poster="https://images-assets.nasa.gov/image/0302063/0302063~medium.jpg"
/>

posterQuality

Type: 'max' | 'high' | 'default' | 'low'
Default: 'default'

When using the default Vimeo poster image, set the posterQuality to change the size of the placeholder image. This can be useful if displaying the embed at very large or very small sizes.

posterQualityresolution
'low'120px
'default'480px
'high'640px
'max'1280px
<Vimeo id="32001208" posterQuality="low" />

params

You can pass a params prop to set the player parameters supported by Vimeo. This looks like a series of URL search params.

For example, the following params value sets the UI color to red and mutes the audio by default:

<Vimeo id="32001208" params="color=ff0000&muted=1" />

playlabel

Type: string
Default: 'Play'

By default, the play button in the embed has an accessible label set to “Play”. If you want to customise this, for example to match the language of your website, you can set the playlabel prop:

<Vimeo id="32001208" playlabel="Play the video" />

Standalone installation

If you only need the <Vimeo> component, you can install the package directly instead of the main astro-embed package:

Terminal window
npm i @astro-community/astro-embed-vimeo

The <Vimeo> component can then be imported as:

import { Vimeo } from '@astro-community/astro-embed-vimeo';