--- title: "YouTube block" description: "An embedded YouTube video with the media width, aspect ratio and alignment controls." requested_language: fr language: en translation_notice: "This page isn't translated yet" url: https://docs.systhema.app/fr/payload/blocks/youtube version: unreleased (main) docs_index: https://docs.systhema.app/fr/llms.txt --- > This page isn't translated yet. Showing English. The YouTube block embeds a YouTube video in a figure, with the same width and aspect-ratio controls as the other media blocks. ![The youtube block fields in the Payload editor](./images/youtube.light.webp) ## Where it is offered Offered in the `root`, `region` and `fragment` tiers, so editors can place it on a page, inside a Section, Feature or Gallery body, and inside cards, columns and accordions. It is never offered in the `slot` tier. ## Fields | Field | Type | Label | Default | Notes | | ----------------- | ---------- | ----------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `_inCard` | `checkbox` | | | | | `_tier` | `select` | | | Options: `root` (Root), `region` (Region), `fragment` (Fragment), `slot` (Slot), `stack` (Stack) | | `align` | `radio` | Alignment | `left` | Shown when `siblingData?.[mediaKey]`; Required; Shown when `sized(siblingData)&&(siblingData?.widthType==="pixels"\|\|siblingData?.widthType==="percentage"&&typeof siblingData?.widthPercentage==="number"&&siblingData.widthPercentage<100)`; Options: `left` (Left), `center` (Center), `right` (Right) | | `aspectRatio` | `select` | Aspect Ratio | `16/9` | Shown when `siblingData?.[mediaKey]`; Required; Shown when `siblingData?.[mediaKey]`; Options: `auto` (Auto), `21/9-md` (21:9 on desktop, 4:3 on mobile), `21/9` (cinema - 21:9), `16/9` (video - 16:9), `4/3` (landscape photo - 4:3), `3/2` (landscape photo - 3:2), `1/1` (square - 1:1), `3/4` (portrait photo - 3:4), `4/5` (instagram - 4:5), `9/16` (vertical video - 9:16) | | `cardWidth` | `radio` | Width alignment | `default` | Shown when `siblingData?.[mediaKey]`; Required; Shown when `hasValue(siblingData)&&siblingData?._inCard===true`; Options: `default` (Default), `card` (Card width) | | `poster` | `upload` | Poster image (optional) | | Shown when `siblingData?.url`; Related to `uploads` | | `url` | `text` | Paste Youtube URL | | Required | | `widthPercentage` | `number` | | `100` | Shown when `siblingData?.[mediaKey]`; Required; Shown when ``visible(siblingData)&&siblingData?.[`${dimension}Type`]==="percentage"`` | | `widthPixels` | `number` | | `512` | Shown when `siblingData?.[mediaKey]`; Required; Shown when ``visible(siblingData)&&siblingData?.[`${dimension}Type`]==="pixels"`` | | `widthType` | `radio` | Width | `percentage` | Shown when `siblingData?.[mediaKey]`; Required; Shown when `visible(siblingData)`; Options: `percentage` (%), `pixels` (px) | | `width` | `radio` | Width alignment | `default` | Shown when `siblingData?.[mediaKey]`; Required; Shown when `(hasValue?hasValue(siblingData):true)&&siblingData?._tier!=="fragment"`; Options: `default` (Default), `container` (Container), `screen` (Screen) | `url` stores the YouTube URL and `poster` optionally stores an image upload. Advanced settings control width, aspect ratio and alignment. Unlike Image and Video, YouTube has no object-fit, parallax or link fields. As a direct child of a card it gains a **Card width** option; see [Media inside a card](https://docs.systhema.app/fr/payload/blocks/card.md#media-inside-a-card). ## Rendered output Renders the embed inside a [Figure](https://docs.systhema.app/fr/components/figure.md). ## Converter `youtubeConverter` extracts a video ID and supported query parameters from `url`. An empty or unrecognized URL renders nothing. It places the titled iframe in MediaWrapper and Figure, uses `16/9` when the aspect ratio is absent or auto, and adds a play overlay when a populated poster is present. Fragment tier ignores breakout widths. ## Customizing Import `YoutubeBlock` from `@systhemaui/payload/blocks` as the starting schema for a project block. Register the definition and your renderer through `customBlocks`, using `type: 'block'` and the editor tiers you intend to support. A distinct slug creates a new block; a converter registered under the existing `youtube` slug takes precedence over the built-in converter. Keep the fields that renderer reads, including populated relationships and nested editor states. See [Registering blocks](https://docs.systhema.app/fr/payload/blocks.md#registering-blocks) for the configuration pattern and [Converters](https://docs.systhema.app/fr/payload/custom-blocks/converters.md) for the renderer contract. A project converter used in client-mode live preview also needs [browser registration](https://docs.systhema.app/fr/payload/frontend/live-preview/client-mode.md). ## Related - [Video block](https://docs.systhema.app/fr/payload/blocks/video.md) - [Embed block](https://docs.systhema.app/fr/payload/blocks/embed.md)