How to use and display the ACF Gallery field

About the Gallery field

The ACF Gallery field is a field type in the Advanced Custom Fields (ACF) plugin. The ACF Gallery field allows you to select multiple images for a single field from the WordPress Media Library (unlike the ACF Image field, which only supports a single image). Developers commonly use it for all kinds of galleries, or when they need to display a custom set of images on a page.

Extensions

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

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 ACF Gallery field has 3 different Return Formats: Image Array, Image URL, and Image ID. Which is exactly like the Image field, but the response is always an array. With an array, items have a type related to the chosen Return Format. This doesn't affect the field look or the options for site admin. Because the Gallery Return Format controls what data you get in the code. We mean here when you request the ACF Gallery field from the WordPress database using the get_field function.

Our suggestion would be to use the 'Image ID' option, as it's the preferred option with the best performance. Avoid using the 'Image URL' option, unless you need it for a specific reason. As it doesn't allow you to receive any details about the image, only the URL, which isn't sufficient in most cases.

Behind the ACF scenes

The ACF Gallery field acts exactly like the ACF Image field, with one major difference, it stores an array of image IDs in the Post Meta of the page or post item, when the Image field stores only one image ID.

In this way, the ACF Gallery field works as a mediator between the Media Library and yourself. It provides an intuitive UI to choose multiple images from your Media Library. But inside it doesn't actually store the images separately. It uses a kind of mark to 'attach' or 'relate' the images (or attachments if you will) from the Media Library for the page or post.

Display Gallery field with PHP code

To display the Gallery field we need to turn the selected images from the field into img tags.

The code will be different depending on the selected Return Type. Below we provided examples, that will help you create the output. But keep in mind that to turn it into an interactive gallery you'll need to write your own CSS/JavaScript code.

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

<?php

// don't forget to replace 'gallery' with your field name
$images = get_field('gallery');
// can be one of the built-in sizes ('thumbnail', 'medium', 'large', 'full' or a custom size)
$size = 'full';
if ($images) {
    foreach ($images as $imageId) {
        echo wp_get_attachment_image($imageId, $size);
    }
}

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

<?php

// don't forget to replace 'gallery' with your field name
$images = get_field('gallery');
// can be one of the built-in sizes ('thumbnail', 'medium', 'large', 'full' or a custom size)
$size = 'full';
if ($images) {
    foreach ($images as $imageData) {
        // displays the image. Each %s in the string will be replaced with the related argument
        printf("<img src='%s' alt='%s'>",
            esc_url($imageData['sizes'][$size]), esc_attr($imageData['alt']));
    }
}

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

<?php

// don't forget to replace 'gallery' with your field name
$images = get_field('gallery');
if ($images) {
    foreach ($images as $imageURL) {
        // displays the image. Each %s in the string will be replaced with the related argument
        printf("<img src='%s'>",
            esc_url($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. 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 Gallery field with a shortcode

Now, I'll show you how to display an ACF Gallery field using a shortcode.

We can solve this by using the famous WordPress shortcodes. They look the same, they also have plain English words in square brackets: [some-name]. Also, they can accept "arguments" and behind the scenes WordPress associates every shortcode with a PHP function.

No coding is needed for today, which means we also won't be writing any PHP functions. Instead, we'll use a great free plugin, called ACF Views. It provides the functionality to display an ACF Gallery field using auto-generated shortcodes.

The plugin supports all ACF fields and also allows you to display default posts and custom posts on pages. But we'll focus on the ACF Gallery field for now. 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 Gallery field.

To follow along you'll need to install the ACF Views plugin on your WordPress website, don't forget 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

As soon as you've activated the ACF Views plugin a new tab is available in your admin menu, called "ACF Views" go ahead and click on it.

Click on 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 has a list of ACF fields assigned to it, so it's possible to create many View items that display different fields (or a set of fields) for different posts/pages.

Name your View, it should be short and descriptive as this is also the name that will be shown in the Views list making it easier to find. We've called our View "Page gallery".

Assigning fields

When assigning new fields in your View. Click the 'Add Field' button and select your 'Group' from the dropdown. In my case, the group is called "Page fields". Now select the target Field from the dropdown, we've selected "Page gallery".

Note: The field type is shown in the brackets for easy identification. So you can easily know the type of any field in the dropdown.

In this case, you should see "(gallery)". Continue by selecting an 'Image Size' from the dropdown, we've chosen 'Full'.

If you use the Pro version of the plugin, then also Masonry and Lightbox options are available for you. See the screenshot below.

Every View supports an unlimited amount of ACF fields, but in our case, we'll only assign a single field.

Click on the 'Publish' button to save and publish your View. When your View is published you'll notice that Shortcodes were generated and available 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"]

Press the 'Copy to clipboard' button for the first shortcode.

Step 2. Paste the shortcode in place

We're nearly there, now that everything is prepared we're ready to display the ACF Gallery field.

Visit your target page that has the ACF Gallery field, (be sure to attach a few images), then paste the copied shortcode anywhere you'd like in the page content. You can paste the shortcode using 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.

Open the page to see the result, in the case that everything was done correctly you should see all the attached images from the ACF Gallery field displayed.

In case you don't see your gallery, then you'll need to go back and edit the page. Confirm that you have attached some images to the ACF Gallery field, then reload the page. If for some reason you still don't see anything, then go back to edit your View and confirm you've selected the correct field "Group" from the list.

Final thoughts

We've shown you how to use the ACF Gallery field, its options, and two ways to display it. So now you can easily use the field anywhere.

Don't forget that a View in the ACF Views plugin supports all field types and you can style the output by adding some CSS rules within the View (see the CSS code field in the "Advanced" tab). What's great about this is that the CSS is only loaded on pages where you're using the shortcode.

In the same tab, you can add JS code, which is also super useful as in the case with galleries. With the Basic version, you'll need to use your own CSS (and likely JavaScript) to turn the default look into an interactive gallery. With the Pro version, Masonry and Lightbox options will be available for you out of the box, i.e. without coding at all.

We hope you found this article useful. For more information about the ACF Views plugin, visit the official website.