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

Astro
MDX

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

<YouTube id="TtRtkTzHVBU" />

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:

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"
/>

`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.

`posterQuality`	resolution
`'low'`	120px
`'default'`	480px
`'high'`	640px
`'max'`	1280px

<YouTube id="TtRtkTzHVBU" posterQuality="low" />

`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" />

`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"
/>

Standalone installation

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

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

pnpm add @astro-community/astro-embed-youtube

yarn add @astro-community/astro-embed-youtube

The <YouTube> component can then be imported as:

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