ACF oEmbed field, How to use and display it

Use the oEmbed field in ACF to embed media into your WordPress site. Designed to work with the built in oEmbed feature of WordPress, it'll allow you to easily embed third-party content, such as videos, images, social media posts, etc., into your WordPress posts or pages by simply pasting the URL of the content. WordPress automatically recognizes the URL format and fetches the appropriate embed code for the given resource. Think of it as a simpler version of the "Preview loading" feature in social media, on sites like Facebook.com or Linkedin.com. When you write a new post, and paste a link then it'll pull in the image, title and except.

Let's look at what is happening in the background.

The ACF oEmbed field simplifies the process of embedding third-party content within custom fields. It provides a user-friendly interface that allows content editors to enter the URL of the resource they want to embed, and ACF takes care of generating the appropriate embed code for that resource. This eliminates the need for users to manually find, copy and paste the embed codes or the need to worry about the technical details of embedding content and/or media.

When you create an oEmbed field in ACF, you can define the Embed Size. These settings help control the appearance and behavior of the embedded content within your website. But don't be too concerned, feel free to ignore the embed size for now.

Now that we know what happens behind the scenes, let's continue with the steps to display embedded content.

We know that when you paste the URL from Twitter or YouTube as an example, into the ACF oEmbed field (while editing a post or page) it returns a string containing the embed HTML obtained by the wp_oembed_get() function. That's great and all, but how do you display that content?

ACF Views is the answer, it creates the HTML markup and spits out a shortcode, you can then copy and paste that into your content, widget or really anywhere within WordPress (that supports shortcodes).

It's the most user-friendly way to display ACF fields, a method that's easy to maintain, because there isn't much coding involved and one where you won't need to modify your theme either.

Let's dive in.

If you're planning to follow along, then search for ACF Views using the built-in Plugin install feature. Keep in mind that you should have Advanced Custom Fields active, as ACF Views is an add-on to it.

When activating the ACF Views plugin a new item appears in the admin menu, called "ACF Views". The item has several sub-items, but in our case, we'll be working only with the one called "ACF Views".

Click that menu item to open the Views page and then click the 'Add New' button to create a View.

On the new page give your View a name, it can be anything that describes the View. I've called my View "video library".

It’s time to assign the oEmbed field to your View. Click on the ‘Add Field’ button and select your ‘Group’ from the dropdown. In my case, I've called the group “Videos from YouTube”.

Then continue to select the target field from the list. I've selected “Video”.

Click the “Publish” button to save and publish your View. Shortcodes are then generated and shown on the right of the View edit screen. Read more about the different shortcodes and their uses in the ACF Views docs.

Copy the first shortcode without the object-id parameter to the clipboard.
E.g. [acf_views view-id="456" name="video library"]

You're almost done.

Go to your target page (the page where you’ve located your ACF fields) then click on the title to edit the page, and paste the copied shortcode anywhere you’d like in the page content.

For Gutenberg editor: click on the plus button in the top bar and choose the "Shortcode" block from the list, then paste your shortcode in the block. If you have Gutenberg as your default editor, you could likely just paste the shortcode, it'll know which block to use.

Now, all that’s left to do is to fill in the field with the video url.

In my case, I have a ‘Video’ oEmbed field and from the default $post$ group the 'Title' and 'Excerpt'.

If you don’t see your video thumb with the title and excerpt, then go back and edit the page. For instance, make sure you’ve filled the fields and saved the page, if they are indeed filled, then go further back to your View edit, where you assigned the fields. Then double check they're assigned from the correct field group. Consequently, if you've left the fields unfilled on the page or post then there won't be anything to display.

As you can see, displaying the embedded content with a shortcode is simple and straight forward, especially when you have a lot of fields to display.

Now, let's look at the other method using PHP code.

The PHP code below can be used to display an oEmbed.

// todo use your field name instead of 'oembed'
$oembedHtml = get_field('oembed') ?: '';

if ($oembedHtml) {
    printf('<div class="embed-container">%s</div>', $oembedHtml);
}

In the code below, we've added extra parameters to the iframe src which gives a little more control over what happens to the video player controls or aspect ratio of the content.

// todo use your field name instead of 'oembed'
$oembedHtml = get_field('oembed') ?: '';

if ($oembedHtml) {
    preg_match('/src="(.+?)"/', $oembedHtml, $matches);
    $src = $matches[1] ?? '';

    $params = [
        // todo use your arguments here
        'controls' => 0,
        'hd' => 1,
        'autohide' => 1
    ];
    $newStr = add_query_arg($params, $src);
    $oembedHtml = str_replace($src, $newStr, $oembedHtml);

    printf('<div class="embed-container">%s</div>', $oembedHtml);
}

Note, in this code example we've only shown how to display a single oEmbed field. If you have more fields, then you'd need to write the relevant code to display it.

To get additional information, watch the video below and read the official ACF article.

With some additional CSS styles, you can now create responsive embeds.

Note: Each provider like Vimeo, Dailymotion, Google Maps or YouTube, may need different CSS styles. Therefore it's best to create styles for each specific case.

In this tutorial, we’ve shown you how to use and display ACF oEmbed fields in two ways, first with a simple shortcode and then with some PHP code. The shortcode method is of course much easier, requires no coding and removes the hassle of maintaining the PHP code in future.

Note, that a View can contain any number of fields of different types, which means you could extend your View at any time, ACF Views supports all available field types with extended settings for complex field types, like ACF Repeater.

For more info about the plugin we used in our shortcode example, visit the official plugin page.

Now go embed some media!