How to use and display the ACF Image field

About the Image field

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.

But keep in mind, that one Image field allows to select only single image. So to add a new image to your page you need to create a new field. If you want to select and store multiple images within one field, use the ACF Gallery field, which is designed for this.

Extensions

Another important limitation is the file extension. You can upload only files with the allowed extensions. For images allowed are .jpg, .jpeg, .png, .gif, and .ico. You can find the list of allowed extensions for all file types on the related wordpress.org page. If you want to allow uploading for example .svg, you'll need to use special hooks.

There is no way to upload not image files to the ACF Image field. For example, you can't upload .doc, or .pdf even with the hooks. For this goal, you need to use the ACF File field, which is designed for it.

So, if you want to know the hook names to add another image extension that the one listed above, we provide a code snippet, which allows .svg uploading on your website. You can modify it for your target extension or use it as is for .svg. The code can be added to your functions.php.

<?php
         add_filter('upload_mimes', function ($mimes) {
            $mimes['svg'] = 'image/svg+xml';

            return $mimes;
        });

        add_filter('wp_check_filetype_and_ext', function ($data, $file, $filename, $mimes) {
            $filetype = wp_check_filetype($filename, $mimes);

            return [
                'ext' => $filetype['ext'],
                'type' => $filetype['type'],
                'proper_filename' => $data['proper_filename']
            ];
        }, 10, 4);

Return Formats

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.

Behind the ACF 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). Then 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 using the 'ID' Return Format, as it fits the database format and doesn't require extra work from the ACF plugin to retrieve it.

Avoid duplicates

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 why you need to completely remove an image from your WordPress library. But they're out of the scope of today's article.

Display Image field 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 Image field 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. Read how to display ACF fields without coding to know all benefits of the shortcode approach.

Below we attached a video tutorial that shows how to display ACF fields on a single page using the shortcode way. The video is common for all the ACF field types. More video tutorials on the official YouTube channel.

But feel free to skip the video as below we provide a full step-by-step guide exactly for the ACF Image field.

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 submenu, there are several items, but we'll only need to use the one called 'ACF Views'.

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".

Assigning fields

Now you need to assign a new field to your View. Click the 'Add Field' button and select your 'Group' from the dropdown. In our case, the group is called "Page fields". Then select the target field from the list. In our 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 our case we'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. So 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, and 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.

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.

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

You've learnt how to use the ACF Image field, its options, and two ways to display it. So now you can easily use the field anywhere.

Don't forget that 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.