Video

Video · sample rowDesktopTabletPhoneOpen ↗

Renders VideoBlock from @bison-lab/ui: an optional eyebrow, heading and description, then the video in a rounded frame, and an optional caption under it.

Video from is the kit’s type cards (the same control as a feed’s card source): YouTube or Vimeo (embed, the default, and what a row saved with no source renders as) or Upload (upload).

• A link renders as a facade: the poster (or, for YouTube with no poster, YouTube’s own thumbnail) and a play button. Nothing is requested from YouTube or Vimeo until a visitor presses play, so a page pays nothing for a video nobody plays. The click loads youtube-nocookie.com or player.vimeo.com (dnt=1) and starts the video. parseVideoUrl reads share, watch, embed and Shorts links, a t= start time, and an unlisted Vimeo hash; anything else is refused on save with the field’s own message.
• An upload is a native <video controls preload="metadata" playsinline> with the poster and an optional WebVTT captions track. Play silently on a loop turns it into a muted ambient loop (for short animations) that plays only while on screen and has its own pause button (WCAG 2.2.2); a visitor who prefers reduced motion gets the poster and a play button instead.

aspect is the frame: landscape (16:9, the default), standard (4:3), square (1:1) or portrait (9:16). width is contained (a reading measure) or wide (the page measure). A row with no playable source (an empty or unrecognised link, or an upload with no file) renders nothing.

Media must accept video. An upload comes from the site’s Media collection, which takes images only by default. Pass createMedia({ mimeTypes: ["image/*", "video/mp4", "video/webm", "text/vtt"] }) to allow video and captions, and keep files short (under about 20 MB); long videos belong on YouTube or Vimeo.

Usage

payload.config.ts / collections

import { VideoBlock } from "@bison-lab/payload-blocks";

// In the collection's `blocks` array:
VideoBlock

blocks/registry.ts

import { VideoBlockRenderer } from "@bison-lab/payload-blocks/react";

// In the site's registry:
video: VideoBlockRenderer,

Fields

Field	Type	Notes
eyebrow	text	Small label above the heading. The heading is optional.
title	text
description	textarea
source	radio	Labelled “Video from”. One of embed, upload.
url	text	Labelled “YouTube or Vimeo link”. Paste the video's share link. Nothing loads from YouTube or Vimeo until a visitor presses play.
file	upload	Labelled “Video file”. An MP4 (H.264) from Media. Keep it short and under about 20 MB; long or large videos belong on YouTube or Vimeo. From the media collection.
captions	upload	Labelled “Captions”. Optional WebVTT (.vtt) captions. Videos with speech need them for visitors who cannot hear it. From the media collection.
loop	checkbox	Labelled “Play silently on a loop”. For short animations with no sound: plays muted while on screen, with a pause button. Visitors who prefer reduced motion get a play button instead. Default false.
poster	upload	The still shown before play. Optional for YouTube, which supplies one; recommended for Vimeo and uploads. From the media collection.
aspect	select	Match the video's own shape so it has no black bars. One of landscape, standard, square, portrait. Default "landscape".
width	select	Contained sits on a reading width; Wide takes the full page width. One of contained, wide. Default "contained".
caption	text	A line under the video. Optional.
settings	group	Labelled “Block Settings”.
settings.background	select	Labelled “Background”. The surface this section sits on. Page is the plain page background. One of page, card, muted, color, gradient. Default "page".
settings.backgroundColor	text	Labelled “Color”.
settings.backgroundColorDark	text	Labelled “Dark mode color”.
settings.gradientTo	text	Labelled “Gradient end”.
settings.gradientToDark	text	Labelled “Dark mode gradient end”.
settings.gradientDirection	text	Labelled “Gradient direction”.
settings.spacing	select	Labelled “Spacing”. The air above and below this section. Default is the block's own padding; Compact and Spacious replace it. This is the band, not the site-wide spacing in Theme → Appearance. One of compact, default, spacious. Default "default".
settings.anchor	text	Labelled “Anchor”. In-page links can target this section. Leave blank for none.
settings.hidden	checkbox	Labelled “Hidden”. The section stays in the editor and is left off the page. Default false.

* required.