acf pro Archives - Developry Plugins

ACF Gallery Field Tutorial: Create Custom Image Galleries

Krasen Slavov — Sat, 25 Oct 2025 09:00:00 +0000

ACF Gallery Fields enable multiple image uploads and management through drag-and-drop interfaces returning arrays of image data for custom gallery displays. From simple grid layouts and masonry galleries to lightbox integrations and responsive image galleries, the Gallery field eliminates plugin dependencies. This comprehensive tutorial teaches Gallery field setup, image array manipulation, responsive grid layouts, lightbox library integration, and advanced techniques creating professional custom image galleries with ACF PRO.

Creating Gallery Field

Add Gallery Field via ACF UI:

Custom Fields → Field Groups
Add Field
Field Type: Gallery (ACF PRO)
Configuration:
- Field Label: Project Gallery
- Field Name: project_gallery
- Return Format: Array (recommended)
- Library: All (uploaded to post or all)
- Min/Max Images: Set limits
- Insert: Append/Prepend

Field Configuration Options:

Return Format:
- Array: Full image data (recommended)
- URL: Image URLs only
- ID: Attachment IDs only

Library:
- all: All images in media library
- uploadedTo: Only images uploaded to this post

Min/Max:
- Min: 1 (require at least one image)
- Max: 20 (limit to 20 images)

Insert:
- append: Add new images to end
- prepend: Add new images to beginning

Basic Gallery Display

Simple Gallery Grid:


$images = get_field('project_gallery');

if ($images) :
    ?>
    class="image-gallery">
        <?php foreach ($images as $image) : ?>
            class="gallery-item">
                "$image['sizes']['medium']); ?>"
                     alt="$image['alt']); ?>"
                     title="$image['title']); ?>" />
            
        <?php endforeach; ?>
    
<?php endif; ?>

CSS for Grid Layout:

.image-gallery {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
    gap: 20px;
    padding: 20px 0;
}

.gallery-item {
    position: relative;
    overflow: hidden;
    border-radius: 8px;
}

.gallery-item img {
    width: 100%;
    height: 250px;
    object-fit: cover;
    transition: transform 0.3s ease;
}

.gallery-item:hover img {
    transform: scale(1.05);
}

Gallery with Captions

Display Images with Captions:


$images = get_field('project_gallery');

if ($images) :
    ?>
    class="gallery-with-captions">
        <?php foreach ($images as $image) : ?>
            class="gallery-item">
                "$image['sizes']['large']); ?>"
                     alt="$image['alt']); ?>" />

                <?php if ($image['caption']) : ?>
                    
                        <?php echo esc_html($image['caption']); ?>
                    
                <?php endif; ?>
            
        <?php endforeach; ?>
    
<?php endif; ?>

Caption Styling:

.gallery-with-captions {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 30px;
}

.gallery-item figcaption {
    padding: 10px;
    background: #f8f9fa;
    font-size: 14px;
    color: #6c757d;
    text-align: center;
}

GLightbox Integration:

Enqueue GLightbox (functions.php):

function mytheme_gallery_lightbox() {
    // GLightbox CSS
    wp_enqueue_style(
        'glightbox',
        'https://cdn.jsdelivr.net/npm/glightbox/dist/css/glightbox.min.css',
        array(),
        '3.2.0'
    );

    // GLightbox JS
    wp_enqueue_script(
        'glightbox',
        'https://cdn.jsdelivr.net/npm/glightbox/dist/js/glightbox.min.js',
        array(),
        '3.2.0',
        true
    );

    // Initialize lightbox
    wp_add_inline_script('glightbox', '
        document.addEventListener("DOMContentLoaded", function() {
            GLightbox({
                selector: ".glightbox"
            });
        });
    ');
}
add_action('wp_enqueue_scripts', 'mytheme_gallery_lightbox');

Gallery Template with Lightbox:


$images = get_field('project_gallery');

if ($images) :
    ?>
    class="lightbox-gallery">
        <?php foreach ($images as $image) : ?>
            "$image['url']); ?>"
               class="glightbox gallery-item"
               data-gallery="gallery1"
               data-description="$image['caption']); ?>">
                "$image['sizes']['medium']); ?>"
                     alt="$image['alt']); ?>" />
            
        <?php endforeach; ?>
    
<?php endif; ?>

Masonry Gallery Layout

Masonry Grid Gallery:


$images = get_field('project_gallery');

if ($images) :
    ?>
    class="masonry-gallery">
        <?php foreach ($images as $index => $image) :
            // Vary heights for masonry effect
            $tall = ($index % 3 === 0) ? 'tall' : '';
            ?>

            class="gallery-item $tall); ?>">
                "$image['url']); ?>"
                   class="glightbox"
                   data-gallery="masonry">
                    "$image['sizes']['large']); ?>"
                         alt="$image['alt']); ?>" />
                
            

        <?php endforeach; ?>
    
<?php endif; ?>

Masonry CSS:

.masonry-gallery {
    column-count: 3;
    column-gap: 15px;
}

.gallery-item {
    break-inside: avoid;
    margin-bottom: 15px;
}

.gallery-item img {
    width: 100%;
    display: block;
    border-radius: 8px;
}

.gallery-item.tall {
    height: 400px;
}

@media (max-width: 768px) {
    .masonry-gallery {
        column-count: 2;
    }
}

@media (max-width: 480px) {
    .masonry-gallery {
        column-count: 1;
    }
}

Slider Gallery

Image Slider with Navigation:


$images = get_field('project_gallery');

if ($images) :
    ?>
    class="slider-gallery">
        class="slider-container">
            <?php foreach ($images as $index => $image) : ?>
                class="slide $index === 0) ? 'active' : ''; ?>"
                     data-slide="$index); ?>">
                    "$image['sizes']['large']); ?>"
                         alt="$image['alt']); ?>" />

                    <?php if ($image['caption']) : ?>
                        class="slide-caption">
                            <?php echo esc_html($image['caption']); ?>
                        
                    <?php endif; ?>
                
            <?php endforeach; ?>
        

        
        

        class="slider-dots">
            <?php foreach ($images as $index => $image) : ?>
                
            <?php endforeach; ?>
        
    
<?php endif; ?>

Slider JavaScript:

document.addEventListener("DOMContentLoaded", function () {
    const slides = document.querySelectorAll(".slide");
    const dots = document.querySelectorAll(".dot");
    const prevBtn = document.querySelector(".slider-prev");
    const nextBtn = document.querySelector(".slider-next");
    let currentSlide = 0;

    function showSlide(n) {
        slides.forEach((slide) => slide.classList.remove("active"));
        dots.forEach((dot) => dot.classList.remove("active"));

        if (n >= slides.length) currentSlide = 0;
        if (n < 0) currentSlide = slides.length - 1;

        slides[currentSlide].classList.add("active");
        dots[currentSlide].classList.add("active");
    }

    prevBtn.addEventListener("click", () => {
        currentSlide--;
        showSlide(currentSlide);
    });

    nextBtn.addEventListener("click", () => {
        currentSlide++;
        showSlide(currentSlide);
    });

    dots.forEach((dot, index) => {
        dot.addEventListener("click", () => {
            currentSlide = index;
            showSlide(currentSlide);
        });
    });
});

Responsive Image Sizes

Use Appropriate Image Sizes:


$images = get_field('project_gallery');

if ($images) :
    ?>
    class="responsive-gallery">
        <?php foreach ($images as $image) : ?>
            class="gallery-item">
                
                    
                    "(max-width: 480px)"
                            srcset="$image['sizes']['thumbnail']); ?>">

                    
                    "(max-width: 768px)"
                            srcset="$image['sizes']['medium']); ?>">

                    
                    "$image['sizes']['large']); ?>"
                         alt="$image['alt']); ?>" />
                
            
        <?php endforeach; ?>
    
<?php endif; ?>

Gallery with Thumbnails

Main Image with Thumbnail Navigation:


$images = get_field('project_gallery');

if ($images) :
    ?>
    class="gallery-with-thumbs">
        
        class="main-image">
            "main-gallery-img"
                 src="$images[0]['sizes']['large']); ?>"
                 alt="$images[0]['alt']); ?>" />
        

        
        class="thumbnail-strip">
            <?php foreach ($images as $index => $image) : ?>
                
            <?php endforeach; ?>
        
    
<?php endif; ?>

Thumbnail Navigation JavaScript:

document.querySelectorAll(".thumb").forEach(function (thumb) {
    thumb.addEventListener("click", function () {
        const fullSrc = this.getAttribute("data-full");
        const altText = this.getAttribute("data-alt");
        const mainImg = document.getElementById("main-gallery-img");

        mainImg.src = fullSrc;
        mainImg.alt = altText;

        document.querySelectorAll(".thumb").forEach((t) => t.classList.remove("active"));
        this.classList.add("active");
    });
});

Lazy Loading Gallery

Performance Optimization:


$images = get_field('project_gallery');

if ($images) :
    ?>
    class="lazy-gallery">
        <?php foreach ($images as $index => $image) :
            // Load first 3 images immediately, lazy load rest
            $loading = ($index < 3) ? 'eager' : 'lazy';
            ?>

            class="gallery-item">
                "$image['sizes']['medium']); ?>"
                     alt="$image['alt']); ?>"
                     loading="$loading); ?>"
                     width="$image['sizes']['medium-width']); ?>"
                     height="$image['sizes']['medium-height']); ?>" />
            

        <?php endforeach; ?>
    
<?php endif; ?>

Filter Gallery by Category

Gallery with Category Filters:


$images = get_field('project_gallery');

if ($images) :
    ?>
    class="filtered-gallery">
        
        class="gallery-filters">
            
            
            
            
        

        
        class="gallery-grid">
            <?php foreach ($images as $image) :
                // Get category from image description
                $category = $image['description'] ?: 'all';
                ?>

                class="gallery-item" data-category="$category); ?>">
                    "$image['sizes']['medium']); ?>"
                         alt="$image['alt']); ?>" />
                

            <?php endforeach; ?>
        
    
<?php endif; ?>

Filter JavaScript:

document.querySelectorAll(".filter-btn").forEach(function (btn) {
    btn.addEventListener("click", function () {
        const filter = this.getAttribute("data-filter");

        document.querySelectorAll(".filter-btn").forEach((b) => b.classList.remove("active"));
        this.classList.add("active");

        document.querySelectorAll(".gallery-item").forEach(function (item) {
            const category = item.getAttribute("data-category");

            if (filter === "all" || category === filter) {
                item.style.display = "block";
            } else {
                item.style.display = "none";
            }
        });
    });
});

Gallery Image Count

Display Image Count:


$images = get_field('project_gallery');

if ($images) :
    $image_count = count($images);
    ?>

    class="gallery-section">
        class="gallery-header">
            Project Gallery
            class="image-count">
                <?php echo esc_html($image_count); ?>
                <?php echo ($image_count === 1) ? 'Image' : 'Images'; ?>
            
        

        class="image-gallery">
            <?php foreach ($images as $image) : ?>
                class="gallery-item">
                    "$image['sizes']['medium']); ?>"
                         alt="$image['alt']); ?>" />
                
            <?php endforeach; ?>
        
    

<?php endif; ?>

Accessing Image Metadata

Full Image Data Available:


$images = get_field('project_gallery');

if ($images) :
    foreach ($images as $image) :
        // Available image data:
        $id = $image['ID'];
        $title = $image['title'];
        $alt = $image['alt'];
        $caption = $image['caption'];
        $description = $image['description'];
        $url = $image['url'];
        $width = $image['width'];
        $height = $image['height'];

        // Image sizes
        $thumbnail = $image['sizes']['thumbnail'];
        $medium = $image['sizes']['medium'];
        $large = $image['sizes']['large'];
        $full = $image['sizes']['full'];

        // Size dimensions
        $thumb_width = $image['sizes']['thumbnail-width'];
        $thumb_height = $image['sizes']['thumbnail-height'];
    endforeach;
endif;
?>

Programmatic Gallery Registration

Register Gallery Field via PHP:

function mytheme_register_gallery_field() {
    if (function_exists('acf_add_local_field_group')) {
        acf_add_local_field_group(array(
            'key'    => 'group_project_gallery',
            'title'  => 'Project Gallery',
            'fields' => array(
                array(
                    'key'    => 'field_project_gallery',
                    'label'  => 'Gallery Images',
                    'name'   => 'project_gallery',
                    'type'   => 'gallery',
                    'return_format' => 'array',
                    'library' => 'all',
                    'min'    => 1,
                    'max'    => 50,
                    'insert' => 'append',
                ),
            ),
            'location' => array(
                array(
                    array(
                        'param'    => 'post_type',
                        'operator' => '==',
                        'value'    => 'portfolio',
                    ),
                ),
            ),
        ));
    }
}
add_action('acf/init', 'mytheme_register_gallery_field');

Best Practices

Always Check for Images:


$images = get_field('project_gallery');

// Good - check before loop
if ($images) {
    foreach ($images as $image) {
        // Display images
    }
}

// Bad - no check, may cause errors
foreach (get_field('project_gallery') as $image) {
    // Display images
}
?>

Optimize Image Sizes:

// Use appropriate size for context
$thumbnail = $image['sizes']['thumbnail']; // 150x150
$medium = $image['sizes']['medium'];       // 300x300
$large = $image['sizes']['large'];         // 1024x1024

Escape All Output:

 echo esc_url($image['url']); ?>
 echo esc_attr($image['alt']); ?>
 echo esc_html($image['caption']); ?>

Conclusion

ACF Gallery Fields enable custom image galleries through drag-and-drop interfaces returning comprehensive image data arrays for flexible display options. Implement responsive grid layouts with CSS Grid, integrate lightbox libraries like GLightbox for full-screen viewing, create masonry galleries with column-count, build image sliders with JavaScript navigation, and optimize performance with lazy loading attributes. Gallery fields eliminate gallery plugin dependencies while providing complete control over gallery styling, functionality, and responsive behavior.

External Links

Call to Action

Gallery configurations need backup protection. Backup Copilot Pro backs up your WordPress gallery field settings and image data automatically. Safeguard your custom galleries—start your free 30-day trial today!

The post ACF Gallery Field Tutorial: Create Custom Image Galleries appeared first on Developry Plugins.

ACF Flexible Content Layouts: Create Modular Page Builders

Krasen Slavov — Mon, 20 Oct 2025 09:00:00 +0000

ACF Flexible Content Fields create drag-and-drop page builders through multiple layout types within a single field allowing editors complete layout control. From text blocks and image galleries to testimonial carousels and call-to-action sections, flexible content eliminates template constraints. This comprehensive guide teaches flexible content setup, layout configuration, get_row_layout() conditional display, nested flexible fields, programmatic registration, and advanced techniques building custom WordPress page builders with ACF PRO.

What Is Flexible Content?

Flexible Content Concept:

Flexible Content (ACF PRO) allows users to choose from multiple layout types and arrange them in any order:

Text Block: Heading, paragraph, alignment
Image Block: Image, caption, size
Video Block: Video URL, thumbnail
Gallery: Multiple images
Testimonial: Quote, author, photo
Call to Action: Heading, text, button

Key Benefits:

Drag-and-drop reordering
Unlimited layout combinations
Different fields per layout type
Complete editor flexibility
No template changes needed

Creating Flexible Content Field

Add Flexible Content via ACF UI:

Custom Fields → Add Field
Field Type: Flexible Content (ACF PRO)
Configuration:
- Field Label: Page Content
- Field Name: page_content
- Button Label: “Add Content Block”
- Min/Max Layouts: Set limits (optional)

Add Layout Types:

Click “Add Layout” for each content type:

Layout 1: Text Block

Layout Name: text_block
Layout Label: Text Block
Sub-fields:
- heading (Text)
- content (Wysiwyg Editor)
- alignment (Select: left/center/right)

Layout 2: Image Block

Layout Name: image_block
Layout Label: Image Block
Sub-fields:
- image (Image)
- caption (Text)
- size (Select: small/medium/large/full)

Layout 3: Gallery

Layout Name: gallery
Layout Label: Gallery
Sub-fields:
- images (Gallery)
- columns (Number)

Basic Flexible Content Loop

Display Layouts:


if (have_rows('page_content')) :

    while (have_rows('page_content')) : the_row();

        if (get_row_layout() == 'text_block') :
            // Text Block Layout
            $heading = get_sub_field('heading');
            $content = get_sub_field('content');
            $alignment = get_sub_field('alignment');
            ?>

            class="content-block text-block text-$alignment); ?>">
                <?php if ($heading) : ?>
                    <?php echo esc_html($heading); ?>
                <?php endif; ?>

                <?php if ($content) : ?>
                    class="content">
                        <?php echo wp_kses_post($content); ?>
                    
                <?php endif; ?>
            

        <?php elseif (get_row_layout() == 'image_block') :
            // Image Block Layout
            $image = get_sub_field('image');
            $caption = get_sub_field('caption');
            $size = get_sub_field('size');
            ?>

            class="content-block image-block size-$size); ?>">
                <?php if ($image) : ?>
                    
                        "$image['sizes'][$size]); ?>"
                             alt="$image['alt']); ?>" />
                        <?php if ($caption) : ?>
                            <?php echo esc_html($caption); ?>
                        <?php endif; ?>
                    
                <?php endif; ?>
            

        <?php elseif (get_row_layout() == 'gallery') :
            // Gallery Layout
            $images = get_sub_field('images');
            $columns = get_sub_field('columns');
            ?>

            class="content-block gallery-block columns-$columns); ?>">
                <?php if ($images) : ?>
                    class="gallery-grid">
                        <?php foreach ($images as $image) : ?>
                            class="gallery-item">
                                "$image['sizes']['medium']); ?>"
                                     alt="$image['alt']); ?>" />
                            
                        <?php endforeach; ?>
                    
                <?php endif; ?>
            

        <?php endif;

    endwhile;

endif;
?>

Complete Page Builder Example

Advanced Layout Types:


if (have_rows('page_content')) :

    while (have_rows('page_content')) : the_row();

        // Text Block
        if (get_row_layout() == 'text_block') :
            get_template_part('template-parts/blocks/text-block');

        // Hero Section
        elseif (get_row_layout() == 'hero') :
            $title = get_sub_field('hero_title');
            $subtitle = get_sub_field('hero_subtitle');
            $background = get_sub_field('background_image');
            $button_text = get_sub_field('button_text');
            $button_link = get_sub_field('button_link');
            ?>

            class="content-block hero-block"
                     style="background-image: url($background['url']); ?>);">
                class="hero-content">
                    <?php if ($title) : ?>
                        <?php echo esc_html($title); ?>
                    <?php endif; ?>

                    <?php if ($subtitle) : ?>
                        class="subtitle"><?php echo esc_html($subtitle); ?>
                    <?php endif; ?>

                    <?php if ($button_text && $button_link) : ?>
                        "$button_link); ?>" class="btn btn-primary">
                            <?php echo esc_html($button_text); ?>
                        
                    <?php endif; ?>
                
            

        // Two Column Layout
        elseif (get_row_layout() == 'two_columns') :
            $left_content = get_sub_field('left_column');
            $right_content = get_sub_field('right_column');
            ?>

            class="content-block two-columns">
                class="row">
                    class="col-left">
                        <?php echo wp_kses_post($left_content); ?>
                    
                    class="col-right">
                        <?php echo wp_kses_post($right_content); ?>
                    
                
            

        // Testimonials
        elseif (get_row_layout() == 'testimonials') :
            if (have_rows('testimonial_items')) :
                ?>
                class="content-block testimonials-block">
                    class="testimonials-grid">
                        <?php while (have_rows('testimonial_items')) : the_row();
                            $quote = get_sub_field('quote');
                            $author = get_sub_field('author');
                            $company = get_sub_field('company');
                            $photo = get_sub_field('photo');
                            ?>

                            class="testimonial">
                                
                                    <?php echo esc_html($quote); ?>
                                

                                class="testimonial-author">
                                    <?php if ($photo) : ?>
                                        "$photo['sizes']['thumbnail']); ?>"
                                             alt="$author); ?>" />
                                    <?php endif; ?>

                                    class="author-info">
                                        <?php echo esc_html($author); ?>
                                        <?php if ($company) : ?>
                                            <?php echo esc_html($company); ?>
                                        <?php endif; ?>
                                    
                                
                            

                        <?php endwhile; ?>
                    
                
            <?php endif;

        // Call to Action
        elseif (get_row_layout() == 'cta') :
            $heading = get_sub_field('cta_heading');
            $text = get_sub_field('cta_text');
            $button = get_sub_field('cta_button');
            $background_color = get_sub_field('background_color');
            ?>

            class="content-block cta-block"
                     style="background-color: $background_color); ?>;">
                class="cta-content">
                    <?php if ($heading) : ?>
                        <?php echo esc_html($heading); ?>
                    <?php endif; ?>

                    <?php if ($text) : ?>
                        <?php echo esc_html($text); ?>
                    <?php endif; ?>

                    <?php if ($button) : ?>
                        "$button['url']); ?>" class="btn btn-large">
                            <?php echo esc_html($button['title']); ?>
                        
                    <?php endif; ?>
                
            

        <?php endif;

    endwhile;

endif;
?>

Using Template Parts

Organize Layouts in Separate Files:

main-template.php:


if (have_rows('page_content')) :
    while (have_rows('page_content')) : the_row();

        $layout = get_row_layout();

        // Load template part based on layout name
        get_template_part('template-parts/blocks/' . $layout);

    endwhile;
endif;
?>

template-parts/blocks/text_block.php:


$heading = get_sub_field('heading');
$content = get_sub_field('content');
$alignment = get_sub_field('alignment');
?>

class="content-block text-block text-$alignment); ?>">
    <?php if ($heading) : ?>
        <?php echo esc_html($heading); ?>
    <?php endif; ?>

    <?php if ($content) : ?>
        class="content">
            <?php echo wp_kses_post($content); ?>
        
    <?php endif; ?>

Programmatic Flexible Content Registration

Register via PHP:

function mytheme_register_flexible_content() {
    if (function_exists('acf_add_local_field_group')) {
        acf_add_local_field_group(array(
            'key'    => 'group_page_builder',
            'title'  => 'Page Builder',
            'fields' => array(
                array(
                    'key'    => 'field_page_content',
                    'label'  => 'Page Content',
                    'name'   => 'page_content',
                    'type'   => 'flexible_content',
                    'button_label' => 'Add Content Block',
                    'layouts' => array(
                        'text_block' => array(
                            'key'   => 'layout_text_block',
                            'name'  => 'text_block',
                            'label' => 'Text Block',
                            'display' => 'block',
                            'sub_fields' => array(
                                array(
                                    'key'   => 'field_heading',
                                    'label' => 'Heading',
                                    'name'  => 'heading',
                                    'type'  => 'text',
                                ),
                                array(
                                    'key'   => 'field_content',
                                    'label' => 'Content',
                                    'name'  => 'content',
                                    'type'  => 'wysiwyg',
                                ),
                            ),
                        ),
                        'image_block' => array(
                            'key'   => 'layout_image_block',
                            'name'  => 'image_block',
                            'label' => 'Image Block',
                            'display' => 'block',
                            'sub_fields' => array(
                                array(
                                    'key'   => 'field_image',
                                    'label' => 'Image',
                                    'name'  => 'image',
                                    'type'  => 'image',
                                    'return_format' => 'array',
                                ),
                                array(
                                    'key'   => 'field_caption',
                                    'label' => 'Caption',
                                    'name'  => 'caption',
                                    'type'  => 'text',
                                ),
                            ),
                        ),
                    ),
                ),
            ),
            'location' => array(
                array(
                    array(
                        'param'    => 'post_type',
                        'operator' => '==',
                        'value'    => 'page',
                    ),
                ),
            ),
        ));
    }
}
add_action('acf/init', 'mytheme_register_flexible_content');

Conditional Layout Display

Show Layouts Based on Conditions:


$layout_index = 0;

if (have_rows('page_content')) :
    while (have_rows('page_content')) : the_row();
        $layout_index++;
        $layout = get_row_layout();

        // Add special class to first layout
        $first_class = ($layout_index === 1) ? 'first-block' : '';

        // Add container to specific layouts only
        $needs_container = in_array($layout, array('text_block', 'cta'));
        ?>

        class="content-block $layout); ?> $first_class); ?>">
            <?php if ($needs_container) : ?>
                class="container">
            <?php endif; ?>

            <?php
            // Display layout content
            get_template_part('template-parts/blocks/' . $layout);
            ?>

            <?php if ($needs_container) : ?>
                
            <?php endif; ?>
        

    <?php endwhile;
endif;
?>

Nested Flexible Content

Flexible Content Within Flexible Content:


if (have_rows('page_content')) :
    while (have_rows('page_content')) : the_row();

        if (get_row_layout() == 'section_with_blocks') :
            $section_title = get_sub_field('section_title');
            ?>

            class="multi-block-section">
                <?php echo esc_html($section_title); ?>

                <?php
                // Nested flexible content
                if (have_rows('section_blocks')) :
                    while (have_rows('section_blocks')) : the_row();

                        if (get_row_layout() == 'feature') :
                            $feature_icon = get_sub_field('icon');
                            $feature_title = get_sub_field('title');
                            $feature_text = get_sub_field('text');
                            ?>

                            class="feature">
                                <?php if ($feature_icon) : ?>
                                    "$feature_icon['url']); ?>" alt="" />
                                <?php endif; ?>
                                <?php echo esc_html($feature_title); ?>
                                <?php echo esc_html($feature_text); ?>
                            

                        <?php endif;

                    endwhile;
                endif;
                ?>
            

        <?php endif;

    endwhile;
endif;
?>

Dynamic Classes and Styling

Add Custom Classes from Fields:


if (have_rows('page_content')) :
    while (have_rows('page_content')) : the_row();

        $layout = get_row_layout();
        $custom_class = get_sub_field('custom_css_class');
        $background_color = get_sub_field('background_color');
        $padding = get_sub_field('padding_size');

        $classes = array(
            'content-block',
            $layout,
            $custom_class,
            'padding-' . $padding,
        );

        $style = $background_color ? 'background-color: ' . esc_attr($background_color) : '';
        ?>

        class="$classes))); ?>"
                 <?php if ($style) : ?>style="$style; ?>"<?php endif; ?>>
            <?php get_template_part('template-parts/blocks/' . $layout); ?>
        

    <?php endwhile;
endif;
?>

Layout Clone Field

Reuse Layout Configurations:

// Create base layout configuration
acf_add_local_field_group(array(
    'key' => 'group_block_settings',
    'title' => 'Block Settings',
    'fields' => array(
        array(
            'key' => 'field_block_settings',
            'label' => 'Block Settings',
            'name' => 'block_settings',
            'type' => 'group',
            'sub_fields' => array(
                array(
                    'key' => 'field_margin',
                    'label' => 'Margin',
                    'name' => 'margin',
                    'type' => 'select',
                    'choices' => array(
                        'none' => 'None',
                        'small' => 'Small',
                        'medium' => 'Medium',
                        'large' => 'Large',
                    ),
                ),
                array(
                    'key' => 'field_animation',
                    'label' => 'Animation',
                    'name' => 'animation',
                    'type' => 'select',
                    'choices' => array(
                        'none' => 'None',
                        'fade-in' => 'Fade In',
                        'slide-up' => 'Slide Up',
                    ),
                ),
            ),
        ),
    ),
));

// Clone in flexible content layouts
array(
    'key' => 'field_settings_clone',
    'label' => 'Settings',
    'name' => 'settings',
    'type' => 'clone',
    'clone' => array('field_block_settings'),
)

Best Practices

Organize Layout Files:

theme/
├── template-parts/
│   └── blocks/
│       ├── text_block.php
│       ├── image_block.php
│       ├── gallery.php
│       ├── hero.php
│       ├── testimonials.php
│       └── cta.php

Use Consistent Naming:

Layout names: snake_case (text_block, image_block)
Layout labels: Title Case (Text Block, Image Block)
CSS classes: kebab-case (text-block, image-block)

Escape Output:

 echo esc_html($text); ?>
 echo esc_url($url); ?>
 echo esc_attr($class); ?>
 echo wp_kses_post($html_content); ?>

Conclusion

ACF Flexible Content Fields create modular page builders through multiple layout types, get_row_layout() conditional display, and drag-and-drop reordering eliminating rigid template structures. Register layouts programmatically with acf_add_local_field_group(), organize layout templates in separate files with get_template_part(), implement nested flexible content for complex page structures, and add custom classes and styling options for design flexibility. Flexible content empowers editors to build custom page layouts without developer intervention maintaining consistent design patterns.

External Links

Call to Action

Page builder configurations need reliable backups. Backup Copilot Pro protects your WordPress flexible content layouts and custom field data automatically. Safeguard your modular page structures—start your free 30-day trial today!

The post ACF Flexible Content Layouts: Create Modular Page Builders appeared first on Developry Plugins.

ACF and Gutenberg: Integrating Custom Fields with Block Editor

Krasen Slavov — Fri, 10 Oct 2025 09:00:00 +0000

ACF Blocks (ACF PRO) enable custom Gutenberg block creation through PHP registration combining block editor flexibility with ACF field power. From simple content blocks with custom fields to complex layouts with InnerBlocks and block templates, ACF Blocks eliminate React JavaScript requirements. This comprehensive guide teaches ACF Block registration, field integration, render callbacks, block templates, InnerBlocks support, and advanced techniques creating custom WordPress Gutenberg blocks with familiar ACF workflows.

What Are ACF Blocks?

ACF Blocks Concept (ACF PRO 5.8+):

ACF Blocks create custom Gutenberg blocks using PHP:

No React required: Use PHP templates
ACF Fields: Familiar field interface
Block Controls: Native block toolbar
Reusable: Save and reuse block instances
Flexible: Full block editor integration

Block vs Field Group:

Traditional Field Group:
- Attached to post type
- Single metabox location
- Fixed field order

ACF Block:
- Insertable anywhere in content
- Multiple instances per post
- Drag-and-drop positioning
- Reusable patterns

Basic Block Registration

Register Simple Block (functions.php):

function mytheme_register_acf_blocks() {
    // Check ACF function exists
    if (function_exists('acf_register_block_type')) {
        acf_register_block_type(array(
            'name' => 'testimonial',
            'title' => __('Testimonial', 'mytheme'),
            'description' => __('A custom testimonial block', 'mytheme'),
            'render_template' => get_template_directory() . '/blocks/testimonial.php',
            'category' => 'common',
            'icon' => 'format-quote',
            'keywords' => array('testimonial', 'quote', 'review'),
        ));
    }
}
add_action('acf/init', 'mytheme_register_acf_blocks');

Block Registration Parameters

Complete Configuration:

acf_register_block_type(array(
    // Required
    'name' => 'testimonial',
    'title' => __('Testimonial'),

    // Content
    'description' => __('A testimonial block'),
    'render_template' => 'blocks/testimonial.php',
    'render_callback' => 'mytheme_render_testimonial',

    // Appearance
    'category' => 'common',
    'icon' => 'format-quote',
    'keywords' => array('testimonial'),

    // Behavior
    'mode' => 'preview',
    'align' => 'full',
    'supports' => array(
        'align' => true,
        'mode' => false,
        'multiple' => true,
        'jsx' => true,
    ),

    // Style
    'enqueue_style' => get_template_directory_uri() . '/blocks/testimonial.css',
    'enqueue_script' => get_template_directory_uri() . '/blocks/testimonial.js',
    'enqueue_assets' => 'mytheme_testimonial_assets',

    // Advanced
    'post_types' => array('post', 'page'),
    'example' => array(
        'attributes' => array(
            'mode' => 'preview',
            'data' => array(
                'author' => 'John Doe',
                'quote' => 'Amazing service!',
            ),
        ),
    ),
));

Parameter Explanations:

name: Unique slug (no spaces)
title: Display name in inserter
description: Block description
render_template: PHP file path
render_callback: PHP function name
category: Block category
icon: Dashicon or custom SVG
keywords: Search terms
mode: 'preview', 'edit', or 'auto'
align: Default alignment
supports: Block capabilities
enqueue_style: CSS file URL
enqueue_script: JS file URL
post_types: Allowed post types
example: Preview data

Creating Block Template

Testimonial Block Template (blocks/testimonial.php):


/**
 * Testimonial Block Template
 *
 * @param array $block The block settings and attributes
 * @param string $content The block inner HTML (empty)
 * @param bool $is_preview True during AJAX preview
 * @param int $post_id The post ID this block is saved to
 */

// Get ACF fields
$author = get_field('author');
$company = get_field('company');
$quote = get_field('quote');
$photo = get_field('photo');
$rating = get_field('rating');

// Block ID
$block_id = 'testimonial-' . $block['id'];

// Block classes
$class_name = 'testimonial-block';
if (!empty($block['className'])) {
    $class_name .= ' ' . $block['className'];
}
if (!empty($block['align'])) {
    $class_name .= ' align' . $block['align'];
}
?>

"$block_id); ?>" class="$class_name); ?>">
    <?php if ($quote) : ?>
        class="testimonial-quote">
            <?php echo esc_html($quote); ?>
        
    <?php endif; ?>

    class="testimonial-author">
        <?php if ($photo) : ?>
            "$photo['sizes']['thumbnail']); ?>"
                 alt="$author); ?>"
                 class="author-photo" />
        <?php endif; ?>

        class="author-info">
            <?php if ($author) : ?>
                class="author-name"><?php echo esc_html($author); ?>
            <?php endif; ?>

            <?php if ($company) : ?>
                class="author-company"><?php echo esc_html($company); ?>
            <?php endif; ?>

            <?php if ($rating) : ?>
                class="rating">
                    <?php for ($i = 0; $i < $rating; $i++) : ?>
                        class="star">★
                    <?php endfor; ?>
                
            <?php endif; ?>

Block Field Group

Register Fields for Block:

function mytheme_register_block_fields() {
    if (function_exists('acf_add_local_field_group')) {
        acf_add_local_field_group(array(
            'key' => 'group_testimonial_block',
            'title' => 'Testimonial Block Fields',
            'fields' => array(
                array(
                    'key' => 'field_author',
                    'label' => 'Author',
                    'name' => 'author',
                    'type' => 'text',
                    'required' => 1,
                ),
                array(
                    'key' => 'field_company',
                    'label' => 'Company',
                    'name' => 'company',
                    'type' => 'text',
                ),
                array(
                    'key' => 'field_quote',
                    'label' => 'Quote',
                    'name' => 'quote',
                    'type' => 'textarea',
                    'required' => 1,
                ),
                array(
                    'key' => 'field_photo',
                    'label' => 'Photo',
                    'name' => 'photo',
                    'type' => 'image',
                    'return_format' => 'array',
                ),
                array(
                    'key' => 'field_rating',
                    'label' => 'Rating',
                    'name' => 'rating',
                    'type' => 'range',
                    'min' => 1,
                    'max' => 5,
                    'step' => 1,
                    'default_value' => 5,
                ),
            ),
            'location' => array(
                array(
                    array(
                        'param' => 'block',
                        'operator' => '==',
                        'value' => 'acf/testimonial',
                    ),
                ),
            ),
        ));
    }
}
add_action('acf/init', 'mytheme_register_block_fields');

Block Categories

Built-in Categories:

'common' - Common
'formatting' - Formatting
'layout' - Layout
'widgets' - Widgets
'embed' - Embeds

Custom Category:

function mytheme_block_categories($categories) {
    return array_merge(
        $categories,
        array(
            array(
                'slug' => 'custom-blocks',
                'title' => __('Custom Blocks', 'mytheme'),
                'icon' => 'admin-customizer',
            ),
        )
    );
}
add_filter('block_categories_all', 'mytheme_block_categories', 10, 2);

Block Icons

Dashicon Icon:

'icon' => 'format-quote'
'icon' => 'admin-users'
'icon' => 'heart'

Custom SVG Icon:

'icon' => ''

Icon with Background:

'icon' => array(
    'background' => '#7e70af',
    'foreground' => '#fff',
    'src' => 'format-quote',
)

Block Modes

Mode Options:

// Preview mode (default)
'mode' => 'preview'

// Edit mode (show fields)
'mode' => 'edit'

// Auto switch
'mode' => 'auto'

Allow Mode Switching:

'supports' => array(
    'mode' => true, // Allow users to toggle
)

Block Alignment

Set Default Alignment:

'align' => 'full'
'align' => 'wide'
'align' => 'center'

Enable Alignment Control:

'supports' => array(
    'align' => true, // Enable alignment toolbar
    'align' => array('left', 'center', 'right'), // Specific alignments
)

InnerBlocks Support

Enable Nested Blocks:

'supports' => array(
    'jsx' => true,
)

Template with InnerBlocks:

class="container-block">
    class="container-header">
        <?php echo esc_html(get_field('title')); ?>
    

    class="container-content">

Block Example (Preview)

Provide Preview Data:

'example' => array(
    'attributes' => array(
        'mode' => 'preview',
        'data' => array(
            'author' => 'Jane Smith',
            'company' => 'Acme Corp',
            'quote' => 'This is an amazing product!',
            'rating' => '5',
        ),
    ),
)

Enqueue Block Assets

Separate CSS/JS Files:

'enqueue_style' => get_template_directory_uri() . '/blocks/testimonial.css',
'enqueue_script' => get_template_directory_uri() . '/blocks/testimonial.js',

Asset Callback Function:

'enqueue_assets' => function() {
    wp_enqueue_style('testimonial-block', get_template_directory_uri() . '/blocks/testimonial.css');
    wp_enqueue_script('testimonial-block', get_template_directory_uri() . '/blocks/testimonial.js', array('jquery'), '1.0', true);
}

Render Callback

Use Function Instead of Template:

'render_callback' => 'mytheme_render_testimonial'

function mytheme_render_testimonial($block, $content = '', $is_preview = false, $post_id = 0) {
    $author = get_field('author');
    $quote = get_field('quote');

    echo '';
    echo '' . esc_html($quote) . '
';
    echo '' . esc_html($author) . '';
    echo '
';
}

Block Wrapper Attributes

Add Custom Attributes:


$block_attributes = get_block_wrapper_attributes(array(
    'class' => 'additional-class',
    'data-custom' => 'value',
));
?>

?php echo $block_attributes; ?>>

Restrict Block to Post Types

Limit Where Block Appears:

'post_types' => array('post', 'page')
'post_types' => array('portfolio')

Multiple Block Instances

Control Block Duplication:

'supports' => array(
    'multiple' => true, // Allow multiple instances
)

'supports' => array(
    'multiple' => false, // Single instance only
)

Block Templates

Pre-populate Post with Blocks:

function mytheme_register_template() {
    $post_type_object = get_post_type_object('portfolio');
    $post_type_object->template = array(
        array('acf/testimonial', array(
            'author' => 'Default Author',
            'quote' => 'Add your testimonial here',
        )),
        array('core/paragraph', array(
            'placeholder' => 'Add project description...',
        )),
    );
}
add_action('init', 'mytheme_register_template');

Complete Block Example

Hero Block with Multiple Fields:

// Registration
acf_register_block_type(array(
    'name' => 'hero',
    'title' => __('Hero Section'),
    'render_template' => 'blocks/hero.php',
    'category' => 'layout',
    'icon' => 'cover-image',
    'supports' => array(
        'align' => array('full'),
        'mode' => false,
    ),
));

// Fields
acf_add_local_field_group(array(
    'key' => 'group_hero',
    'title' => 'Hero Block',
    'fields' => array(
        array(
            'key' => 'field_hero_title',
            'label' => 'Title',
            'name' => 'title',
            'type' => 'text',
        ),
        array(
            'key' => 'field_hero_subtitle',
            'label' => 'Subtitle',
            'name' => 'subtitle',
            'type' => 'text',
        ),
        array(
            'key' => 'field_hero_bg',
            'label' => 'Background Image',
            'name' => 'background_image',
            'type' => 'image',
            'return_format' => 'url',
        ),
        array(
            'key' => 'field_hero_button',
            'label' => 'Button',
            'name' => 'button',
            'type' => 'link',
        ),
    ),
    'location' => array(
        array(
            array(
                'param' => 'block',
                'operator' => '==',
                'value' => 'acf/hero',
            ),
        ),
    ),
));

Template (blocks/hero.php):


$title = get_field('title');
$subtitle = get_field('subtitle');
$bg_image = get_field('background_image');
$button = get_field('button');

$class_name = 'hero-block';
if (!empty($block['className'])) {
    $class_name .= ' ' . $block['className'];
}
?>

class="$class_name); ?>"
         style="background-image: url($bg_image); ?>);">
    class="hero-content">
        <?php if ($title) : ?>
            class="hero-title"><?php echo esc_html($title); ?>
        <?php endif; ?>

        <?php if ($subtitle) : ?>
            class="hero-subtitle"><?php echo esc_html($subtitle); ?>
        <?php endif; ?>

        <?php if ($button) : ?>
            "$button['url']); ?>"
               class="hero-button"
               target="$button['target'] ?: '_self'); ?>">
                <?php echo esc_html($button['title']); ?>
            
        <?php endif; ?>

Best Practices

Organize Block Files:

theme/
├── blocks/
│   ├── testimonial/
│   │   ├── block.php
│   │   ├── fields.php
│   │   ├── style.css
│   │   └── script.js
│   └── hero/
│       ├── block.php
│       ├── fields.php
│       └── style.css

Use Block Wrapper:

// Good - uses wrapper
?php echo get_block_wrapper_attributes(); ?>>
    


// Better - adds custom classes
<?php
$attributes = get_block_wrapper_attributes(array(
    'class' => 'custom-class',
));
?>
?php echo $attributes; ?>>

Escape Output:

 echo esc_html($text); ?>
 echo esc_url($url); ?>
 echo esc_attr($attribute); ?>

Conclusion

ACF Blocks enable custom Gutenberg block creation through PHP registration eliminating React JavaScript requirements while maintaining block editor flexibility. Register blocks with acf_register_block_type(), create field groups targeting specific blocks, render with PHP templates accessing fields via get_field(), and implement block supports for alignment, modes, and InnerBlocks. ACF Blocks combine familiar ACF workflows with modern block editor capabilities creating maintainable custom WordPress blocks through PHP.

External Links

Call to Action

Custom block configurations need backup protection. Backup Copilot Pro backs up your WordPress ACF block files and field configurations automatically. Safeguard your Gutenberg blocks—start your free 30-day trial today!

The post ACF and Gutenberg: Integrating Custom Fields with Block Editor appeared first on Developry Plugins.