YouTube block
An embedded YouTube video with the media width, aspect ratio and alignment controls.
On this page
The YouTube block embeds a YouTube video in a figure, with the same width and aspect-ratio controls as the other media blocks.
Where it is offeredLink to this section
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.
FieldsLink to this section
| 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.
Rendered outputLink to this section
Renders the embed inside a Figure.
ConverterLink to this section
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.
CustomizingLink to this section
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 for the configuration pattern and Converters for the renderer contract. A project converter used in client-mode live preview also needs browser registration.