JHTechServices
WordPress ACF Gutenberg PHP

ACF Blocks – Gutenberg Blocks the Easy Way

· 2 min read

Building custom Gutenberg blocks from scratch means diving into React, the block API, block.json, and a build process. For most WordPress projects, that's overkill — especially when you just need a testimonial card, a callout box, or a team member grid.

ACF Blocks lets you define blocks with PHP and render them with a template file, no JavaScript build step required.

What You Need

  • ACF Pro (the free version doesn't include Blocks)
  • WordPress 5.0+
  • A child theme or custom plugin to house your code

Registering a Block

You register ACF Blocks inside acf_init:

add_action( 'acf/init', 'register_acf_blocks' );

function register_acf_blocks() {
    acf_register_block_type( array(
        'name'              => 'testimonial',
        'title'             => __( 'Testimonial' ),
        'description'       => __( 'A customer testimonial block.' ),
        'render_template'   => 'blocks/testimonial.php',
        'category'          => 'formatting',
        'icon'              => 'admin-comments',
        'keywords'          => array( 'testimonial', 'quote' ),
        'supports'          => array( 'align' => false ),
    ) );
}

Creating the Field Group

In the ACF UI, create a field group and set the location rule to Block → is equal to → Testimonial. Add whatever fields you need — a quote textarea, author name, author title, star rating.

The Render Template

Create blocks/testimonial.php in your theme:

<?php
$quote  = get_field( 'quote' );
$author = get_field( 'author_name' );
$title  = get_field( 'author_title' );
?>
<blockquote class="testimonial">
    <p><?php echo esc_html( $quote ); ?></p>
    <footer>
        <strong><?php echo esc_html( $author ); ?></strong>
        <?php if ( $title ) : ?>
            <span><?php echo esc_html( $title ); ?></span>
        <?php endif; ?>
    </footer>
</blockquote>

Preview Mode

ACF Blocks support a preview mode that renders your template in the editor. You can detect it with:

if ( isset( $is_preview ) && $is_preview ) {
    // Render a static preview image or simplified markup
}

Why This Approach Works

For agencies and freelancers, ACF Blocks hit a sweet spot: clients get a native Gutenberg editing experience, developers get a familiar PHP template workflow, and you avoid the maintenance overhead of a full JavaScript block plugin.

This post is a placeholder — full content coming soon.

← Back to Blog