Skip to content
Astro Embed

YouTube

The <YouTube> component generates an embed using the lite-youtube-embed custom element that will load YouTube’s <iframe> only when a user clicks play.

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

Usage

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


<YouTube id="TtRtkTzHVBU" />

You can also pass in a URL in one of the various YouTube formats:

<YouTube id="https://youtu.be/TtRtkTzHVBU" />

The above code produces the following result:

Play

Optional props

In addition to the required id prop, the following props are available to customise how the <YouTube> 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:

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

posterQuality

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

When using the default YouTube 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
<YouTube id="TtRtkTzHVBU" posterQuality="low" />
Play

params

You can pass in a params prop to set the YouTube player parameters. This looks like a series of URL search params.

For example, the following params value sets the start and end times of the video playback:

<YouTube id="TtRtkTzHVBU" params="start=57&end=75" />
Play

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:

<YouTube id="TtRtkTzHVBU" playlabel="Play the video" />

title

Type: string

Set a visible title to overlay on the video.

<YouTube
  id="TtRtkTzHVBU"
  title="The Astro Community: where contributors find a home"
/>
Play

Standalone installation

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

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

The <YouTube> component can then be imported as:

import { YouTube } from '@astro-community/astro-embed-youtube';