Documentation
Page blocksEmbed

Embed Basic

A responsive, accessible sandboxed iframe block for approved HTTPS embeds — installed as a wired Payload block.

v0.1.0Page blockEmbed familyEmbed / media
import type { Block } from 'payload'import { validateEmbedUrl } from '@/blocks/shared/safeUrls'export const EmbedBasic: Block = {  slug: 'embedBasic',  interfaceName: 'EmbedBasicBlock',  fields: [    {      name: 'url',      type: 'text',      required: true,      validate: validateEmbedUrl,      admin: {        description:          'Approved HTTPS embed URL (e.g. https://www.youtube.com/embed/VIDEO_ID).',      },    },    {      name: 'title',      type: 'text',      required: true,      admin: {        description: 'Accessible title announced to screen readers for the embedded frame.',      },    },    {      name: 'aspectRatio',      type: 'select',      required: true,      defaultValue: '16:9',      options: [        { label: '16:9 (widescreen video)', value: '16:9' },        { label: '4:3 (standard video)', value: '4:3' },        { label: '1:1 (square)', value: '1:1' },        { label: '21:9 (ultrawide)', value: '21:9' },      ],    },    {      name: 'caption',      type: 'text',    },    {      name: 'allowFullscreen',      type: 'checkbox',      defaultValue: true,    },  ],  labels: {    plural: 'Embed Basic Blocks',    singular: 'Embed Basic',  },}

Installation

npx payload-components add embed-basic

Copy the files straight from the registry, then wire the Payload fragments by hand:

pnpm dlx shadcn@latest add https://www.payload-components.xyz/r/embed-basic.json

What it installs

Copies 3 source files into your project:

  • src/blocks/EmbedBasic/config.ts
  • src/blocks/EmbedBasic/Component.tsx
  • src/blocks/shared/safeUrls.tsshared

…and makes 4 edits to wire the block into your project:

Registers the blocksrc/collections/Pages/index.ts
Maps the renderersrc/blocks/RenderBlocks.tsx
Regenerates typessrc/payload-types.ts
Regenerates the admin import mapsrc/app/(payload)/admin/importMap.js
safeUrls.ts is the shared field core for this family — every variant composes it. Editing it updates each installed block at once, and re-running an install never overwrites a copy you have changed.

Re-running the install converges: it detects existing wiring, skips it, and records install state in .payload-components/state.json.

Content model

The block accepts approved HTTPS provider embed URLs — paste the provider's embed URL (e.g. https://www.youtube.com/embed/VIDEO_ID, not the watch URL). The iframe renders with a sandbox and a narrowed permissions policy.

Prop

Type

Usage

Add the block to a page. In the Payload admin, open (or create) a Page and add the EmbedBasic block to its layout.
Fill the content. Complete the fields from the content model above — the component ships sample content you can start from.
Publish. Save and publish the page; the block renders through RenderBlocks on the frontend, fully typed — no extra wiring.

Requirements

Target
payload-website-starter
Payload
v3
Next.js
15 / 16
shadcn UI
none

Your project must already expose components.json, src/payload.config.ts, src/blocks/RenderBlocks.tsx, src/collections/Pages/index.ts — the surfaces payload-components add patches. The CLI verifies this against the support matrix before touching anything.