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

About the ACF Gallery field. How to use and display

Time to read: 6 mins


Updated Jan 09, 2023


ACF Plugins Tutorials
Learn about the ACF Gallery field, the field's options, how to use and display it. We'll show you two ways to display the field, one of them without coding. You'll also learn how the field works behind the scenes.

About the Gallery field type

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). It's commonly used for all kinds of galleries, or when you need to display a custom set of images on a page.

Add a Gallery field type in Advanced Custom Fields (ACF)

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 admins, as the Gallery Return Format controls what data you get in the code when you request the ACF Gallery field from the WordPress database using the get_field function.

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

Add multiple images to the ACF Gallery field when editing your page.
Easily remove images by using the 'x', click and drag to reorder them.

ACF Gallery. What's under the hood

The ACF Gallery field acts exactly like the ACF Image field (read more in this article), with one major difference, it stores an array of image IDs in the Post Meta of the page or post item, where 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 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 an ACF Gallery (using 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.

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


// 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:


// 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:


// 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'>",

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 ACF Gallery (using 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], they can also accept "arguments" and behind the scenes WordPress associates every shortcode with a PHP function.

No coding needed for today, that 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.

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.

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

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. I've called my View "Page gallery".

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, I've selected "Page gallery". (Note: The field type is shown in brackets for easy identification) In this case you should see "(gallery)". Continue by selecting an 'Image Size' from the dropdown, I've chosen 'Full'.

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.

Gutenberg block with an ACF Views shortcode.

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.

ACF Gallery field displayed with a shortcode on a page.

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

...and that's how to display an ACF Gallery field (or any ACF field by the way) anywhere using shortcodes, without writing any PHP code. The ACF Views plugin makes it really easy and takes care of all aspects, it automatically generates HTML markup for assigned fields and keeps it up to date when you assign new fields. So all you need to do is create a View by assigning a group, selecting fields from a dropdown, and then to copy and paste the shortcode into place. That's it!

The 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, as most likely you're going to create a slider of some kind. Overall they're plenty of ways to create an image slider, but that's out of scope for this article.

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

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