ACF gallery patterns: per-gallery settings done right

ACF — Advanced Custom Fields — is the field layer that half the WordPress development world builds on, and it spent 2024 at the centre of one of the platform’s ugliest disputes. For a developer building galleries with ACF, two things matter: where ACF actually stands in 2026 (because the situation genuinely changed and a lot of online advice is now wrong), and the field patterns that scale for gallery work. This covers both, leading with the 2024 fork story because you need the current lay of the land before the patterns.

It is the ACF deep-dive of our developer’s guide to building galleries.

The 2026 state of ACF (read this first)

The short version, because the affiliate roundups have it muddled. In October 2024, amid the WP Engine dispute, WordPress.org took over the ACF plugin listing and forked it into Secure Custom Fields (SCF), a free, security-maintained plugin on the .org repository. SCF is genuinely free and maintained, but it does not ship ACF’s Pro fields — no Repeater, no Flexible Content, no Gallery field. In December 2024, ACF regained access to the .org repository, and after a court ruling ACF returned to WP Engine’s stewardship. So as of 2026, both coexist: SCF is the free, .org-hosted, security-focused fork without Pro fields; ACF (and ACF Pro) continues under WP Engine with the full field set, currently around version 6.8.x.

The practical consequence for gallery work is decisive: the gallery-relevant fields — the Gallery field, Repeater, Flexible Content — are Pro features that live in ACF Pro, not in free SCF. So if you are building galleries with ACF, you either need ACF Pro (the licensed product) or you build the equivalent with native WordPress (custom meta, a CPT). The common roundup error — “ACF was removed from WordPress.org” — is wrong as of 2026; the accurate statement is “ACF is back on .org under WP Engine, and SCF is a separate free fork lacking the Pro fields you need for galleries.”

The ACF Gallery field

The most direct tool: ACF Pro’s Gallery field, a UI for selecting and ordering a set of images attached to a post. Its key setting is the return format, which determines what you get in your template code:

• Array — returns full image arrays (URL, sizes, alt, caption, metadata). Most data, heaviest; use when you need the metadata.
• URL — returns just the image URLs. Lightest, but you lose the metadata and the responsive-size data.
• ID — returns attachment IDs. The pattern that scales best: you get IDs and pass them to wp_get_attachment_image(), which generates correct srcset/sizes and respects core’s lazy-loading.

The ID return format is the one to default to for gallery work, precisely because it hands off rendering to wp_get_attachment_image() rather than making you build <img> tags from URLs (where you would lose responsive images, as warned in the pillar). A simple, scalable template:

<?php
$ids = get_field( 'gallery_images' ); // return format: ID
if ( $ids ) {
    echo '<div class="my-gallery">';
    foreach ( $ids as $id ) {
        echo wp_get_attachment_image( $id, 'large' ); // srcset/sizes free
    }
    echo '</div>';
}

Repeater for structured lists

When each gallery item needs more than an image — a caption you control separately, a link, a per-item setting — the Repeater field is the pattern. A Repeater is a group of sub-fields repeated N times, so you can model “image + custom caption + link” per item and loop it. This is more flexible than the Gallery field when items carry structured data, and it is a Pro field (so, ACF Pro, not SCF). The trade-off is performance at scale: a Repeater with many rows and many sub-fields means many meta rows, so for very large galleries the simpler Gallery-field-with-IDs approach can be lighter. Use Repeater when items genuinely need per-item structured data; use the Gallery field when they are just images.

Flexible Content for varied layouts

For pages that mix gallery types — a section that is a grid, then one that is a slider, then a single hero image — Flexible Content is the ACF Pro tool. It lets the editor choose from defined layout blocks and arrange them, each with its own fields. This is powerful for client sites where the editor needs to compose varied image sections without touching code, and it pairs naturally with a page-builder-free, ACF-driven template approach. As with Repeater, it is a Pro field and it has a performance cost at scale, so reserve it for genuinely varied composition needs rather than using it where a simple Gallery field would do.

ACF Blocks for Gutenberg

ACF can also build Gutenberg blocks — ACF Blocks let you create custom blocks using ACF fields for the controls and a PHP template for the render, which is a fast way to make a gallery block without writing the React editor side by hand. The 6.8 line added a block-editor datastore for ACF fields with revisions and autosave, improving the editing experience. For a developer who lives in ACF, ACF Blocks are a comfortable path to a custom gallery block; for one building a distributable plugin, the native block approach (from the block development article) avoids the ACF Pro dependency. Both are valid; the choice is about whether an ACF Pro requirement is acceptable for your distribution model.

Performance: querying ACF gallery fields at scale

ACF stores field values in post meta, and gallery fields can mean a lot of meta — a Repeater gallery especially. At scale this matters: loading a page with many large ACF galleries means many meta queries. Mitigations: prefer the Gallery-field-with-IDs pattern (fewer meta rows than a deep Repeater), avoid loading gallery fields you will not render, and be mindful that ACF’s convenience can hide query cost. For a single page this is invisible; for an archive listing many gallery-bearing posts, or a high-traffic site, it is worth profiling. The native-meta-and-CPT alternative can be lighter for extreme scale, which is the trade-off against ACF’s developer convenience.

When to use native instead of ACF

ACF Pro is a paid dependency, and for a distributable plugin that is a real consideration — you cannot assume your users have ACF Pro. For a distributable gallery plugin, building galleries on native WordPress (a CPT for galleries, post meta or a relationship for the images, the core image functions for rendering) avoids the dependency entirely, which is why serious gallery plugins do not require ACF. For a one-off client site where you already use and license ACF Pro, the Gallery/Repeater/Flexible fields are a fast, comfortable way to build. The decision is distribution model: bespoke client work with ACF Pro already in the stack → use ACF; distributable product or no ACF Pro → build native. FotoGrids, as a distributable plugin, uses its own native field handling rather than requiring ACF, which is the right call for a product but not necessarily for your client site.