iFrame

Released in version 1.21.0

The iFrame block embeds any external or internal URL inside an <iframe> element. It is a fully native Gutenberg block with no third-party JavaScript — all output is generated server-side via render.php.

Key capabilities:

Block Bindings — the URL and accessible title can be bound to external data sources (e.g. a Custom Meta Block / ACF field) so the value resolves dynamically at render time.
Aspect ratio control — choose a preset ratio (16:9, 4:3, 1:1, 9:16, 3:2) or switch to a fixed height.
Sandbox — optionally isolate the iframe with configurable sandbox permissions.
MFB context path — resolve the URL from an MFB (Meta Field Block) context path without modifying the MFB plugin.

Fields

All fields are in the block settings sidebar.

URL

The address to load in the iframe.

Only http:// and https:// URLs are accepted. All other schemes are silently rejected.
Supports Block Bindings — see Block Bindings below.
Supports MFB context path resolution — see MFB Path Workaround below.

Accessible Title

A short description of the iframe content, rendered as the title attribute on the <iframe> element.

Required for accessibility (screen readers announce this text when reaching the iframe).
Supports Block Bindings — the title can be sourced from the same data provider as the URL.

Dimensions panel

Width

A CSS value controlling the iframe container width (default: 100%).

Accepted formats: 100%, 800px, 60vw, etc. Invalid values fall back to 100%.

Use Aspect Ratio (toggle)

When on (default), the iframe height is calculated automatically from the chosen ratio using the CSS aspect-ratio property. This keeps the embed proportional across all screen sizes.

When off, a fixed Height value is used instead.

Aspect Ratio

Preset ratios available when Use Aspect Ratio is on:

Label	Value	Common use
16:9 — Widescreen	`16/9`	YouTube, Vimeo, presentations
4:3 — Standard	`4/3`	Older video, slideshows
3:2 — Photo	`3/2`	Photography galleries
1:1 — Square	`1/1`	Social-style embeds
9:16 — Portrait	`9/16`	Vertical video

Height

Only shown when Use Aspect Ratio is off.

Accepted formats: 400px, 50vh, 20em. Invalid values fall back to 400px.

Behavior panel

Loading

Controls the browser's loading strategy for the iframe.

Lazy (default) — the browser defers loading until the iframe is near the viewport. Improves page performance for embeds below the fold.
Eager — the browser loads the iframe immediately with the rest of the page.

Allow Fullscreen

Adds the allowfullscreen attribute to the iframe element. Required for YouTube, Vimeo, and other video embeds that provide a fullscreen button.

Enabled by default.

Sandbox panel (advanced)

By default, no sandbox is applied. This is intentional — common embeds such as YouTube, Google Maps, and Vimeo require capabilities that a strict sandbox blocks.

Enable Sandbox to add the sandbox attribute. When the sandbox is on with no capabilities selected, the iframe runs in the most restrictive mode (no scripts, no same-origin access, no forms, no popups).

Available capabilities

Checkbox	Token added	What it allows
allow-scripts	`allow-scripts`	Run JavaScript inside the iframe
allow-same-origin	`allow-same-origin`	Treat the iframe as same-origin for storage/cookies
allow-forms	`allow-forms`	Submit forms
allow-popups	`allow-popups`	Open new windows or tabs
allow-modals	`allow-modals`	Show `alert`, `confirm`, and `prompt` dialogs
allow-top-navigation-by-user-activation	`allow-top-navigation-by-user-activation`	Navigate the top-level page, but only in response to a user gesture

Security — allow-scripts + allow-same-origin

Enabling both allow-scripts and allow-same-origin together allows embedded content to escape the sandbox entirely, because the script can remove the sandbox attribute via the DOM. Only use this combination for sources you fully trust. The editor shows a warning when both are selected.

Block Bindings (WordPress 6.5+)

The iFrame block supports the WordPress Block Bindings API introduced in WordPress 6.5.

The url and title attributes can be connected to any registered binding source (e.g. a Custom Meta Block backed by ACF).

How it works

A binding source provides a string value for url or title.
WordPress 6.5+ injects the resolved value into $attributes['url'] (or $attributes['title']) before render.php runs.
render.php validates the resolved URL (scheme check, esc_url_raw) and sanitizes the title before output.

Editor behavior when bound

The corresponding input field is disabled (read-only) in the block inspector.
An info notice is displayed explaining that the field is bound.
The editor preview attempts to show the resolved URL from the binding source.

MFB URL Path Workaround

When the iFrame block is nested inside an MFB (Meta Field Block) object or repeater context, you can resolve the URL directly from MFB context without modifying the MFB plugin.

This field is only shown in the inspector when an mfb/value context is detected.

MFB URL Path (Optional)

A slash-separated path into the current mfb/value context. Examples:

url — a top-level field named url
embed/src — a nested field src inside a group named embed

Resolution order

If MFB URL Path is set and resolves to a non-empty string, that value is used as the URL.
Otherwise the URL attribute is used (which may itself be set by a Block Binding).
If neither produces a valid http/https URL, the block outputs nothing.

Supported MFB node shapes

The path resolver handles the following value formats at the target node:

Plain string
{ value: "..." }
{ value_formatted: "..." }
{ field: { value: "..." } }
{ url: "..." }

Path format

Use / as the delimiter and provide the path relative to the current MFB context root.

Styling

Aspect ratio mode

The block renders a container <div> with aspect-ratio set inline and the yoko-iframe__wrapper--ratio class. The <iframe> inside is positioned absolutely to fill the container.

<div class="wp-block-yoko-core-iframe">
  <div class="yoko-iframe__wrapper yoko-iframe__wrapper--ratio" style="width: 100%; aspect-ratio: 16 / 9;">
    <iframe src="..." title="..." ...></iframe>
  </div>
</div>

Fixed height mode

The container div has no aspect-ratio style and the iframe receives an explicit height via inline style.

<div class="wp-block-yoko-core-iframe">
  <div class="yoko-iframe__wrapper" style="width: 100%;">
    <iframe src="..." title="..." style="width: 100%; height: 400px; ..." ...></iframe>
  </div>
</div>

CSS classes available for theming

Class	Where	Purpose
`.wp-block-yoko-core-iframe`	Outer wrapper	Block-level styles
`.yoko-iframe__wrapper`	Inner container	Shared wrapper styles
`.yoko-iframe__wrapper--ratio`	Inner container	Only present in aspect-ratio mode

Editor preview

The editor renders the live iframe inside the block area (with pointer-events: none so clicks fall through to the block selection layer). Many sites send X-Frame-Options: SAMEORIGIN or Content-Security-Policy: frame-ancestors 'self', which prevents preview loading in the editor. This is expected — the iframe will render correctly on the frontend.

When no URL is configured, the block shows a placeholder indicating that a URL should be entered in the block settings panel.

Troubleshooting

The iframe shows a blank/white area in the editor

The target site likely sends an X-Frame-Options: SAMEORIGIN or frame-ancestors CSP header that blocks embedding in the WordPress admin. The frontend output will still work. You can verify by previewing the page.

My URL is not rendering

Only http:// and https:// URLs are accepted. Check that the URL begins with one of these schemes. Any other protocol (e.g. data:, javascript:, blob:) is rejected as a security measure.

The iframe is not showing the fullscreen button

Enable Allow Fullscreen in the Behavior panel.

The embed does not work with Sandbox enabled

Most third-party embeds (YouTube, Google Maps, Vimeo) require allow-scripts at minimum. Consider disabling Sandbox for these sources, or enabling the specific capabilities the embed requires.

Technical notes (for developers)

Block name: yoko-core/iframe
Rendered server-side via render.php — save() returns null.
Block Bindings support:
- url and title attributes have "role": "content" in block.json.
- The block_bindings_supported_attributes_yoko-core/iframe filter registers both attributes.
- __experimentalConnections: true is declared in supports for editor compatibility.
URL security: Only http and https schemes pass through. URL is sanitized with esc_url_raw() on write and esc_url() on output.
Sandbox: Tokens are built from a strict allowlist in yoko_core_iframe_build_sandbox(). No user-supplied strings enter the sandbox attribute directly.
Dimensions: Width and height values are validated against a regex (/^\d+(\.\d+)?(px|em|rem|%|vw|vh|vmin|vmax|ch|ex)?$/) before output.
MFB context: The block declares usesContext: ["mfb/value", "mfb/allValues", "mfb/rootField"] for path resolution.

Fields​

URL​

Accessible Title​

Dimensions panel​

Width​

Use Aspect Ratio (toggle)​

Aspect Ratio​

Height​

Behavior panel​

Loading​

Allow Fullscreen​

Sandbox panel (advanced)​

Available capabilities​

Block Bindings (WordPress 6.5+)​

How it works​

Editor behavior when bound​

MFB URL Path Workaround​

MFB URL Path (Optional)​

Resolution order​

Supported MFB node shapes​

Styling​

Aspect ratio mode​

Fixed height mode​

CSS classes available for theming​

Editor preview​

Troubleshooting​

The iframe shows a blank/white area in the editor​

My URL is not rendering​

The iframe is not showing the fullscreen button​

The embed does not work with Sandbox enabled​

Technical notes (for developers)​