WPLake > Blog > About the ACF image field. How to use and display

About the ACF image field. How to use and display

Time to read: 7 mins

-

Updated Jan 09, 2023

-

ACF Plugins Tutorials
You'll know about the ACF image field, available options and how to use it. We'll show two ways to display the field, one of them using shortcodes. Also you'll know how it works behind the scenes.

About the image field type

Image field type is one of many possible field types in the Advanced Custom Fields (ACF) plugin. The image field allows you to select any image from the WordPress Media Library or to upload a new one.

Though WordPress Posts and Pages have a built-in Featured Image field, this field only allows a single image for the entire post/page, which is limiting. Using ACF image fields you can 'attach' multiple images to your post/page.

Easily add an image field to any ACF group using the 'Add Field' button and selecting 'Image' in the 'Field Type' dropdown.

The Image field type has 3 different Return Formats: Image Array, Image URL and Image ID. This won't affect how the field looks or options for site admins, however the Image Return Format controls what data you receive in the code when you request this image from the WordPress Database using the get_field function.

I suggest that you choose the 'Image ID' option, as it's the best option for performance. Steer clear of the 'Image URL' option, (unless you need it for a specific reason) because it won't allow you to get any details about the image, only the url, which really isn't enough.

After adding an image field for the target page, admins can 'Add Image' by choosing an image or upload a new one.
After assigning the image it's still possible to change it. Hover your cursor on the image and click the 'Pen' icon to amend image details (e.g. caption) or click by the 'Cross' icon to 'unassign' it from the field.

ACF Image. Behind the scenes

Here's a look at behind the scenes. When you're choosing an image it saves an ID of the selected image in the Post Meta of the current Page (or Post/CPT item). So you can select the same image on many different pages and it won't create duplicates of that image.

When you're adding a new image using any image field, ACF physically uploads that image to your WordPress installation (to the wp-content/uploads folder), creates a new Attachment (with this image) and saves the ID of the attachment to the current Post/Page meta.

The ID of an image is saved to the database regardless of the 'Return Format' option. So the 'Return Format' option only controls what data you receive in code, but in any case only the ID of an image (attachment) will be saved to the database. That's why I've recommended to use the 'ID' Return Format, as it fits the database format and doesn't require extra work from the ACF plugin to retrieve it.

So every new upload creates a new attachment in your Media Library. WordPress can't compare the new image to those already uploaded, which means it'll create another Attachment even if you're uploading the same image again. This is why it's so important to give images clear names and to first search the Media Library before uploading a new image, otherwise you'll have a lot of duplicates of the same image and in turn you'll also use more space on your web hosting account, not to mention the headaches down the line.

Unassigning an image from an image field doesn't remove the image from your WordPress installation, it'll keep the image file in your Media Library, even when you've removed it from all pages/posts where the image field is located. In fact there are only a few reasons when you need to completely remove an image from your WordPress library, but that is outside the scope of today's article.

Display ACF image with PHP code

To display the Image field we need to turn the selected image into the img tag.

The code will be different depending on the selected Return Type. Below we provided examples.

1. PHP code to display the Image field with the "ID" Return Format:

// don't forget to replace 'image' with your field name
$imageID = get_field('image');
// can be one of the built-in sizes ('thumbnail', 'medium', 'large', 'full' or a custom size)
$size = 'full';

if ($imageID) {
    // creates the img tag
    echo wp_get_attachment_image($imageID, $size);
}

2. PHP code to display the Image field with the "Array" Return Format:

<?php

// don't forget to replace 'image' with your field name
$imageData = get_field('image');
// can be one of the built-in sizes ('thumbnail', 'medium', 'large', 'full' or a custom size)
$size = 'full';

if ($imageData) {
    // displays the image. Each %s in the string will be replaced with the related argument
    printf("<img src='%s' alt='%s'>",
        esc_attr($imageData['size'][$size]), esc_attr($imageData['alt']));
}

3. PHP code to display the Image field with the "URL" Return Format:

// don't forget to replace 'image' with your field name
$imageURL = get_field('image');

if ($imageURL) {
    // displays the image. Each %s in the string will be replaced with the related argument
    printf("<img src='%s'>",
        esc_attr($imageURL));
}

With the "URL" Return Format we can't control the image size and are not able to get any additional information besides the URL, so you've to steer clear of this option. It's better always to choose the "ID" Return Format.

You can read more about the field in the official ACF article.

Display ACF image with a shortcode

Shortcodes are a powerful WordPress feature. In fact they're just key phrases that WordPress associates with a PHP function. They look like this with words in square brackets: [some-name] and can accept arguments for example [some-name first-argument="first-value"].

But we're not going to write any PHP code. We'll use a great free plugin called ACF Views to display image fields without coding using generated shortcodes.

The ACF Views plugin allows you to display posts and their ACF fields using shortcodes. As you can imagine the plugin has a wide range of capabilities and also supports all ACF field types, but we'll focus on displaying images for today.

To follow along; install the ACF Views plugin on your WordPress site and remember to activate it (you'll also need the ACF (free) plugin installed and active) then continue to the next steps below.

Step 1. Creating a View

When you've activated the ACF Views plugin you'll see a new item in your admin menu, called "ACF Views".

In the sub menu there are several items, but we'll only need to use the one called 'ACF Views'.

Your list will have the same look but without any View items.

Visit the ACF Views tab, click the 'Add New' button to create a View.

Note: The term "View" is the name given for the special Post Type the plugin provides. Every View is a list of ACF fields to display, so you may have many different Views to display different fields (or sets of fields) for different posts/pages.

Give a name for your View. It can be anything that describes the View, this is the name that will be displayed in the list of Views making it easier to find. I've called my View "Page side image".

Now you need to assign a new field to your View. Click the 'Add Field' button and select your 'Group' from the dropdown. In my case the group is called "Page fields". Then select the target field from the list. In my case the field is called "Side image". (Note: The field type is shown in brackets for easy identification). In this case you should see the type is an "image", continue to choose an 'Image Size' from the list of sizes available, in my case I've chosen 'Full'.

Every View supports an unlimited amount of ACF fields, but in our case we'll use only one.

Click on the 'Publish' button to save and publish your View . After your View is published you'll notice that Shortcodes were generated in a block on the right side of your View edit screen. Every View has its own shortcode with a unique ID (the shortcode structure is the same for all Views, but arguments are unique).

[acf_views view-id="xxxx" name="x"]

Click on the 'Copy to clipboard' button for the first shortcode.

Step 2. Paste the shortcode in place

Okay, so now everything should be ready to display the image field. Visit the target page (with the image field), make sure the field has an image attached, then paste the shortcode anywhere you'd like in the page content. To paste the shortcode with the Gutenberg editor, click on the plus button and choose the "Shortcode" block from the list. Paste your shortcode in the block and click the 'Update' button to save your post/page.

Gutenberg block with an ACF Views shortcode.

Visit the page to see the result, and if you've done everything correctly then you should see your ACF image displayed in the content.

ACF image field displayed with a shortcode on a page.

If you can't see your image, then go back and edit the page. Make sure you've attached an image to the ACF image field because if the field is empty it'll have nothing to display.

Final thoughts

With this way you can display ACF images (and pretty much any ACF field) anywhere using shortcodes, and without having to write any PHP code. The ACF Views plugin does the heavy lifting by automatically generating HTML markup for assigned fields so you don't need to take care of it at all. Simply create a View, select target fields from a list, copy and paste the shortcode into place and that's it!

You can add more fields of different types to your View (for example, in case you want to display several images with titles on a page) and field values can be styled using the CSS code field (see the View's Advanced Tab), that CSS will only be printed on pages where you're using the shortcode.

I hope this article was helpful. You can find more information about the ACF Views plugin on the official website, there you can find links to the YouTube channel for video tutorials and links to the plugin Documentation that will help you with any questions you may have.

About the Author
Maxim Akimov

Certificated WordPress expert from Ukraine with over 6 years of experience.
Advocate of the BEM methodology and the overall modular approach.
Loves sporting activities, enjoys gyming and plays table tennis regularly.

Table of contents

Got it