Video block
An uploaded video with preload, deferred controls, parallax and an optional link.
On this page
The Video block renders an uploaded video as a figure, with playback, preload, width and parallax controls.
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) |
autoPlay | checkbox | Autoplay | Shown when siblingData?.video&&!siblingData?.poster | |
cardWidth | radio | Width alignment | default | Shown when siblingData?.[mediaKey]; Required; Shown when hasValue(siblingData)&&siblingData?._inCard===true; Options: default (Default), card (Card width) |
controls | checkbox | Controls | true | Shown when siblingData?.video&&!siblingData?.poster&&siblingData?.autoPlay&&!siblingData?.parallax |
linkType | radio | Link Type | none | Shown when siblingData?.[mediaKey]; Required; Shown when the custom field-helper condition passes; Options: none (None), custom (Custom URL), internal (Internal Link) |
newTab | checkbox | Open in new tab | false | Shown when siblingData?.[mediaKey]; Shown when the custom field-helper condition passes |
objectFit | radio | Object Fit | cover | Shown when siblingData?.[mediaKey]; Required; Shown when siblingData?.[mediaKey]&&siblingData?.aspectRatio!=="auto"; Options: cover (Cover), contain (Fit) |
objectPositionX | radio | Horizontal Alignment | center | Shown when siblingData?.[mediaKey]; Shown when siblingData?.[mediaKey]&&siblingData?.aspectRatio!=="auto"; Required; Options: left (Left), center (Center), right (Right) |
objectPositionY | radio | Vertical Alignment | center | Shown when siblingData?.[mediaKey]; Shown when siblingData?.[mediaKey]&&siblingData?.aspectRatio!=="auto"; Required; Options: top (Top), center (Center), bottom (Bottom) |
parallax | checkbox | Enable parallax effect | false | Shown when siblingData?.video&&siblingData?.autoPlay&&!siblingData?.poster |
poster | upload | Poster image (optional) | Shown when siblingData?.video; Related to uploads | |
preload | select | Preload | metadata | Required; Shown when condition(siblingData); Options: metadata (Metadata — first frame only (recommended)), none (None — nothing until play), auto (Auto — download the whole video up front) |
reference | relationship | Choose a page to link to | Shown when siblingData?.[mediaKey]; Required; Shown when the custom field-helper condition passes; Related to pages | |
url | text | Enter a URL | `` | Shown when siblingData?.[mediaKey]; Required; Shown when the custom field-helper condition passes |
video | upload | Select video | Required; Related to uploads | |
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) |
Common fields: width (radio), aspectRatio (select), objectFit (radio), objectPositionX/Y (iconGroup), parallax (checkbox), linkType/url/reference/newTab (Image and Video; Video links require silent-autoplay mode). When width is Default, sub-controls appear: widthType (buttonGroup, % / px), widthPercentage/widthPixels (range), and align (iconGroup).
As a direct child of a card it gains a Card width option; see Media inside a card.
Video playback and weightLink to this section
VideoBlock — and every other block that takes an uploaded video, i.e. the hero blocks and FeatureBlock — carries a preload select (metadata / none / auto, default metadata) alongside autoPlay / controls. It maps straight onto <video preload>: auto downloads the whole file during page load, which on a large hero video is the single most expensive thing in the LCP window; metadata fetches just enough for the first frame and the duration. Content stored before this field existed renders as metadata, not the auto that used to be hardcoded — preload is an advisory hint with no visual consequence, so those pages look identical and simply stop pulling megabytes nobody asked for. Autoplaying videos load regardless of the setting. Background heroes take one polymorphic image-or-video upload, so they expose no preload control and inherit the metadata default.
Videos rendered with native controls get them on first interaction rather than at first paint (deferControls on <Video> — see Video); the play affordance stays keyboard-operable and labelled throughout. This removes the layout shift the control bar caused when it materialised after metadata load. Autoplaying videos with controls are deferred too — that is the configuration the shift was measured on — but since they have no play gesture of their own, their controls appear on the visitor's first completed discrete input anywhere on the page — a pointer release, a keypress, or an assistive technology's click (see the WCAG 2.2.2 notes on the Video component). One configuration keeps its control bar at first paint by design: a video with a poster image, where the poster overlay covers the element until it is clicked, so the arrival is hidden anyway.
Inside a client-mode live preview, videos are downgraded to preload="none"; see Client mode caveats.
Rendered outputLink to this section
Renders a Figure with a Video inside.
ConverterLink to this section
videoConverter requires a populated video upload. With a poster it renders a native video behind a MediaOverlay, disables autoplay and enables controls. Without a poster it uses Video with deferred controls. A link is accepted only for autoplay without controls or a poster, even if stale link fields remain stored. Fragment tier suppresses breakout widths.
CustomizingLink to this section
Import VideoBlock 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 video 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.