oEmbed

Paste any oEmbed-compatible URL — YouTube, Vimeo, Twitter/X, SoundCloud, Spotify — and the field fetches and caches the embed data via the WordPress oEmbed API. Shows a live preview in the admin so editors see the result before saving.

★

Pro field

oEmbed requires the Extra Fields for ACF Pro license.

Settings

Setting	Default	Options	Description
Allowed Providers	(empty)	Comma-separated domains	Restrict to specific providers, e.g. `youtube.com, vimeo.com`. Empty = any oEmbed provider.
Max Width	`0`	Integer	Constrain embed width in pixels. `0` = no limit.
Max Height	`0`	Integer	Constrain embed height in pixels. `0` = no limit.
Cache Duration	`1 day`	`1h` · `1d` · `1w` · `1m`	How long resolved embed data is cached.
Show Preview	`true`	on/off	Show live embed preview in the admin when a URL is entered.
Return Format	`object`	`object` · `url` · `html`	What `get_field()` returns.

Return values

`return_format: 'object'`

$embed = get_field('promo_video');
// [
//   'url'       => 'https://www.youtube.com/watch?v=abc123',
//   'provider'  => 'YouTube',
//   'title'     => 'Product Demo',
//   'thumbnail' => 'https://i.ytimg.com/vi/abc123/hqdefault.jpg',
//   'html'      => '<iframe src="..." ...></iframe>',
//   'width'     => 480,
//   'height'    => 270,
// ]

`return_format: 'url'`

$url = get_field('promo_video');
// "https://www.youtube.com/watch?v=abc123"

`return_format: 'html'`

$html = get_field('promo_video');
// '<iframe width="480" height="270" src="https://www.youtube-nocookie.com/embed/abc123" ...></iframe>'

Usage

Rendering the embed HTML

$embed = get_field('featured_video'); // return_format: 'object'

if ($embed && $embed['html']) {
    echo '<div class="video-embed">';
    echo $embed['html']; // already safe HTML from oEmbed API
    echo '</div>';
}

Responsive embed wrapper

$html = get_field('promo_video'); // return_format: 'html'

if ($html) {
    echo '<div class="video-wrap" style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">';
    // Make iframe fill the wrapper — left/top/width/height must stay inline on the iframe element
    $html = preg_replace('/width="[^"]*"/', 'width="100%"', $html);
    $html = preg_replace('/height="[^"]*"/', 'style="position:absolute;top:0;left:0;width:100%;height:100%;"', $html, 1);
    echo $html;
    echo '</div>';
}

Using the thumbnail as a preview poster

$embed = get_field('course_intro');

if ($embed) {
    echo '<div class="video-poster" data-embed="' . esc_attr($embed['html']) . '">';
    echo '<img src="' . esc_url($embed['thumbnail']) . '" alt="' . esc_attr($embed['title']) . '">';
    echo '<button class="play-btn" aria-label="Play video">&#9654;</button>';
    echo '</div>';
}