YouTube

The <YouTube> component generates an embed using the lite-youtube 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:

`playlistId`

Type: string

Set a YouTube playlist ID to load the playlist player when the embed is played. The id prop is still required and sets the video used for the poster image.

<YouTube id="TtRtkTzHVBU" playlistId="PL-G5r6j4GptH5JTveoLTVqpp7w2oc27Q9" />

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

`showTitle`

Type: boolean
Default: true

Set to false to hide the visible title overlay. The title is still used as the accessible label for the embed.

<YouTube id="TtRtkTzHVBU" title="The Astro Community" showTitle={false} />

`staticFallback`

Type: boolean
Default: true

Before JavaScript loads, the embed shows the poster image and a link to the video on YouTube. Set to false to render nothing until JavaScript loads.

<YouTube id="TtRtkTzHVBU" staticFallback={false} />

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