Gallery field render options

By default, Advanced Views displays the Gallery field using a row of <img> tags. You can customize the Layout template to change how it's rendered:

Note: Ensure in the provider group setting that the field return format is set to Image Array or Image ID. Choosing the Image URL doesn’t provide the necessary image dimensions.

1. Grid Gallery

Example of the Grid, taken from our ACF Gallery article.

The CSS grid feature is the easiest way to display Gallery images in a grid.

The example code below shows how to set this up. Change '2' to your desired number of columns in the grid-template-columns rule, and adjust the gap, which controls the space between items, from 20px to your preferred value:

Twig template:

{% if gallery.value %}
    <div class='acf-view__gallery'>
        {% for image_item in gallery.value %}
            <img class='acf-view__image' src="{{ image_item.value }}"
                 width="{{ image_item.width }}" height="{{ image_item.height }}" alt="{{ image_item.alt }}"
                 decoding="{{ image_item.decoding }}" loading="{{ image_item.loading }}"
                 srcset="{{ image_item.srcset }}" sizes="{{ image_item.sizes }}">
        {% endfor %}
    </div>
{% endif %}

CSS code:

#layout__gallery {
 display: grid;
 grid-template-columns: 1fr;
 gap: 20px;
}

@media screen and (min-width:992px) {
 #layout__gallery {
  grid-template-columns: repeat(2, 1fr);
 }
}

2. Masonry Gallery (Pro)

From the Gallery layout dropdown, select the Classic or Flat masonry option and press the Update button.

The Classic masonry employs the Macy.js, while Flat uses a Flat Masonry script from Lightsource.

Pro tip: You can apply both Masonry and Lightbox to the same gallery field simultaneously to provide a visually appealing preview and allow for a detailed display on click.

Optional: After saving, switch to the CSS & JS tab, and fine-tune the instance settings:

Macy.js

Example of the Macy.js, taken from our ACF Gallery article.

In the Masonry instance settings, you can fine-tune the number of columns, the gap between items (margin), and the responsive behavior. Check the Macy.js documentation to learn more.

var gallery = this.querySelector('.avf-layout__gallery');
if (gallery) {
	/* https://github.com/bigbite/macy.js */
	new Macy({
		container: gallery,
		columns: 4,
		margin: {
			x: 0,
			y: 0,
		},
		breakAt: {
			992: 2,
			400: 1,
		},
	});
}

Flat Layout

Example of the Flat masonry, taken from our ACF Gallery article.

The flat masonry is a simple script, which offers only the basic settings, including gap between items and min-row height:

var gallery = this.querySelector('.avf-layout__gallery');
if (gallery) {
	/* https://gitlab.com/lightsource/masonry */
	new AcfViewsMasonry(
		gallery,
		{
			ROW_MIN_HEIGHT: 180,
			GUTTER: 20,
			MOBILE_GUTTER: 10,
			MOBILE_WIDTH: 992,
		}
	);
}

3. Carousel Gallery (Pro)

Example of the Inlline-Carousel, taken from our ACF Gallery article.

From the Gallery layout dropdown, select the Inline-Gallery option and press the Update button.

The Inline-Gallery option employs the Carousel feature of the LightGallery library.

Optional: After saving, switch to the CSS & JS tab, and fine-tune the instance settings:

var gallery = this.querySelector('.avf-layout__gallery');
if (gallery) {
	var container = document.createElement('div');
	container.classList.add('avf-layout__inline-gallery');
	gallery.parentElement.insertBefore(container, gallery);

	/* https://www.lightgalleryjs.com/docs/settings/#lightgallery-core */
	new lightGallery(gallery, {
		container: container,
		showMaximizeIcon: true,
		download: true,
		enableDrag: false,
		allowMediaOverlap: false,
		closable: false,
		plugins: [window.lgThumbnail,],
	}).openGallery();
}

4. Slider Gallery (Pro)

Example of the images slider, taken from our ACF Gallery article.

From the Enable slider dropdown, select the Splide option and press Update. This option employs the Splide library, with the following defaults:

var gallery = this.querySelector('.avf-layout__gallery');
if (gallery) {
	/* https://splidejs.com/guides/options/ */
	new Splide(gallery, {
		type: 'loop',
		perPage: 1,
		perMove: 1,
	}).mount();
}

Displaying captions

In your Layout, copy the Default template content into the Custom template field and modify it as per the example below, by adding the image_item.caption usage:

Twig example:

<avf-layout-66b5d4134a54e class="{{ _layout.classes }} avf-layout 
avf-layout--id--{{ _layout.id }} avf-layout--object-id--{{ _layout.object_id }}">
    {% if gallery.value %}
        <div class="avf-layout__gallery2 splide">
            <div class="splide__track">
                <ul class="avf-layout__gallery2-list splide__list">
                    {% for image_item in gallery.value %}
                        <li class="avf-layout__gallery2-item splide__slide">
                            <img class="avf-layout__gallery2-image" src="{{ image_item.value }}" width="{{ image_item.width }}" height="{{ image_item.height }}" alt="{{ image_item.alt }}" decoding="{{ image_item.decoding }}" loading="{{ image_item.loading }}" srcset="{{ image_item.srcset }}" sizes="{{ image_item.sizes }}">
                            {% if image_item.caption %}<div class="caption">{{ image_item.caption }}</div>{% endif %}
                        </li>
                    {% endfor %}
                </ul>
            </div>
        </div>
    {% endif %}
</<avf-layout-66b5d4134a54e>

Key Details

• Caption Source: The {{ image_item.caption }} tag pulls from WordPress’s native caption field (set in the media library).

• Splide Structure: The outer wrapper must still keep Splide’s structure:

  • div.splide > div.splide__track > ul.splide__list > li.splide__slide

• Conditional Caption: Only renders the <div class="caption"> if a caption exists.

Caption Styling (Optional)

You can style the caption by adding this CSS to your Layout:

.caption {
    text-align: center;
    margin-top: 10px;
    font-size: 14px;
    color: #333;
}

5. Lightbox Gallery (Pro)

Example of the lightbox, taken from our ACF Gallery article.

Lightbox shows a zoom icon on image hover and allows readers to click and open an image in full-screen mode and switch between items if there are others.

Pro tip: You can apply both Masonry and Lightbox to the same gallery field simultaneously to provide a visually appealing preview and allow for a detailed display on click.

From the Enable lightbox dropdown, select the LightGallery or Simple (no settings) option and press Update. The LightGallery option employs the LightGallery library, and has the following defaults:

var gallery = this.querySelector('.avf-layout__gallery');
if (gallery) {
	/* https://www.lightgalleryjs.com/docs/settings/#lightgallery-core */
	new lightGallery(gallery, {
		closeOnTap: true,
		counter: true,
		download: false,
		allowMediaOverlap: false,
		enableDrag: false,
		plugins: [window.lgThumbnail,],
	});
}

6. FAQs

Masonry last image stretching

How to fix it using CSS overrides

Copy the following CSS snippet into your Layouts' -> CSS & JS Tab -> CSS Code field.

// masonry images last image fix stretching
#view .acf-view__image-outer {
    width: fit-content !important;
}