> For the complete documentation index, see [llms.txt](https://wplake.gitbook.io/advanced-views/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wplake.gitbook.io/advanced-views/field-types/media/gallery-field/render-options.md).

# Gallery field render options

By default, Advanced Views [displays the Gallery field](/advanced-views/field-types/media/gallery-field.md) using a row of `<img>` tags. You can [customize the *Layout* template](/advanced-views/layouts/code-fields/custom-template.md) to change how it's rendered:

{% hint style="warning" %}
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.
{% endhint %}

## 1. Grid Gallery

<figure><img src="/files/BuB9A7YT9LWo7j4VEVty" alt=""><figcaption><p>Example of the Grid, taken from our <a href="https://wplake.org/blog/display-acf-gallery-field-with-shortcode/">ACF Gallery article</a>.</p></figcaption></figure>

The [CSS grid feature](https://www.w3schools.com/CSS/css_grid.asp) 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[^1] of columns in the [grid-template-columns](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-columns) rule, and adjust the [gap](https://developer.mozilla.org/en-US/docs/Web/CSS/gap), which controls the space between items, from `20px` to your preferred value:

Twig template:

```twig
{% 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:

```css
#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.&#x20;

The Classic masonry employs the [Macy.js](https://github.com/bigbite/macy.js), while Flat uses a [Flat Masonry script](https://gitlab.com/lightsource/masonry) from Lightsource.&#x20;

{% hint style="info" %}
**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.
{% endhint %}

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

### Macy.js

<figure><img src="/files/rT87anaIAGz6VMomuvJF" alt=""><figcaption><p>Example of the Macy.js, taken from our <a href="https://wplake.org/blog/display-acf-gallery-field-with-shortcode/">ACF Gallery article</a>.</p></figcaption></figure>

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](https://github.com/bigbite/macy.js) to learn more.

```javascript
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

<figure><img src="/files/87EkiOeVJiQIQMG3o66M" alt=""><figcaption><p>Example of the Flat masonry, taken from our <a href="https://wplake.org/blog/display-acf-gallery-field-with-shortcode/">ACF Gallery article</a>.</p></figcaption></figure>

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

```javascript
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)

<figure><img src="/files/RyyhtHbTbsIDqeEj66Bf" alt=""><figcaption><p>Example of the Inlline-Carousel, taken from our <a href="https://wplake.org/blog/display-acf-gallery-field-with-shortcode/">ACF Gallery article</a>.</p></figcaption></figure>

From the **Gallery layout** dropdown, **select** the Inline-Gallery option and press the Update button.&#x20;

{% hint style="info" %}
The Inline-Gallery option employs the [Carousel feature](https://www.lightgalleryjs.com/demos/carousel-gallery/) of the [LightGallery library](https://www.lightgalleryjs.com/).&#x20;
{% endhint %}

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

```javascript
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)

<figure><img src="/files/oFW3sHIhq9ColFkY1Cwe" alt=""><figcaption><p>Example of the images slider, taken from our <a href="https://wplake.org/blog/display-acf-gallery-field-with-shortcode/">ACF Gallery article</a>.</p></figcaption></figure>

From the **Enable slider** dropdown, **select** the Splide option and press Update. This option employs the [Splide library](https://splidejs.com/), with the following defaults:

```javascript
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:

{% code overflow="wrap" %}

```twig
<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>
```

{% endcode %}

#### 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*:

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

## 5.  Lightbox Gallery (Pro)

<figure><img src="/files/agAKr34Gz45wINUqxHMP" alt=""><figcaption><p>Example of the lightbox, taken from our <a href="https://wplake.org/blog/display-acf-gallery-field-with-shortcode/">ACF Gallery article</a>.</p></figcaption></figure>

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.

{% hint style="info" %}
**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.
{% endhint %}

From the **Enable lightbox** dropdown, **select** the LightGallery or Simple (no settings) option and press Update. The LightGallery option employs the [LightGallery library](https://www.lightgalleryjs.com/), and has the following defaults:

```javascript
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

<details>

<summary>Masonry last image stretching</summary>

### How to fix it using CSS overrides

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

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

</details>

[^1]: