ACF + Gutenberg: How to Build ACF Blocks (Full Tutorial)

Dec 19, 2025 |

14 minutes read

Why ACF Blocks Are the Best Way to Extend Gutenberg

The Gutenberg editor has redefined how content is created in WordPress by replacing shortcodes and page builders with a flexible block-based system. While core Gutenberg blocks handle many common use cases, real-world projects often require custom, structured, and reusable components that editors can manage easily. This is where Advanced Custom Fields (ACF) becomes a perfect companion to Gutenberg.

ACF Blocks allow developers to create powerful custom blocks using familiar PHP templates instead of complex JavaScript-heavy block development. By combining ACF with Gutenberg, you can deliver highly customizable blocks that are easy for clients to edit and consistent with your design system.

In this complete tutorial, you’ll learn what ACF Blocks are, when to use them, how they work internally, and how to build your own custom ACF block step by step—following best practices for performance, usability, and scalability.

What Are ACF Blocks?

ACF Blocks are custom Gutenberg blocks built using PHP templates and ACF fields instead of React-based JavaScript. Unlike native Gutenberg blocks that require extensive JavaScript knowledge, ACF Blocks allow developers to define block settings in PHP and manage block content using the familiar ACF interface.

Each ACF block:

Appears as a standard Gutenberg block

Uses ACF fields for content input

Renders output using PHP templates

Supports editor previews and frontend rendering

This approach is especially popular among theme developers who prefer PHP-driven workflows and want faster development without sacrificing flexibility.

Why Use ACF Blocks Instead of Native Blocks?

While native Gutenberg blocks are powerful, ACF Blocks provide several advantages for many projects:

1. Faster Development

- ACF Blocks eliminate the need for complex JavaScript setup. If you already work with PHP and ACF fields, you can create blocks quickly without learning React.

1. Familiar Editing Experience

- Editors interact with ACF fields they already understand—text fields, repeaters, image uploads, toggles—making content management intuitive.

1. Cleaner Codebase

- Block markup lives in PHP template files, keeping logic, layout, and styling well organized.

1. Ideal for Custom Designs

- ACF Blocks are perfect for hero sections, feature grids, testimonials, sliders, call-to-actions, and any layout that needs structured data.

Prerequisites :

Before creating ACF Blocks, ensure the following:

1. WordPress 5.8 or higher
2. Advanced Custom Fields PRO is installed and activated
3. A custom theme or plugin where you can register a block
4. Basic knowledge of PHP and WordPress templates

How ACF Blocks Work Internally :

ACF Blocks rely on WordPress’s block registration system but replace JavaScript rendering with PHP templates.

The process looks like this:

1. You register a block using acf_register_block_type()
2. ACF links the block to a PHP template
3. Editors enter content using ACF fields
4. WordPress renders the block output using PHP

This means the same PHP file controls both editor preview and frontend display.

Step-by-Step: Creating an ACF Block :

Step 1: Register the ACF Block

Add the following code to your theme’s functions.php or a custom plugin:


add_action('acf/init', function () { 
    acf_register_block_type([ 
    	'name'        	=> 'testimonial', 
    	'title'       	=> __('Testimonial'), 
    	'description' 	=> __('A custom testimonial block'), 
    	'render_template' => 'template-parts/blocks/testimonial.php', 
    	'category'    	=> 'formatting', 
    	'icon'        	=> 'format-quote', 
    	'keywords'    	=> ['testimonial', 'quote'], 
    	'supports'    	=> [ 
        	'align' => true, 
        	'anchor' => true, 
    	], 
	]); 
});

This tells WordPress that a new block exists and points it to a PHP template.

Step 2: Create the Block Template

Create a file at:

/template-parts/blocks/testimonial.php

Example template:


<?php
$quote = get_field('quote');
$author = get_field('author');
?>

<div class="testimonial-block">
    <blockquote><?php echo esc_html($quote); ?></blockquote>
    <p class="author"><?php echo esc_html($author); ?></p>
</div>

Step 3: Add ACF Fields to the Block

In the WordPress admin:

1. Go to Custom Fields → Add New
2. Create a Field Group
3. Add fields (Quote, Author, Image, etc.)
4. Set location rule:

- Block → is equal to → Testimonial

These fields will now appear directly inside the Gutenberg editor when the block is selected.

Improving the Editor Preview :

To make the block look better inside the editor, you can detect preview mode:


if (!empty($is_preview)) { 
	echo 'Testimonial Preview'; 
}

You can also load lightweight styles specifically for editor previews to help editors visualize the final design.

Styling ACF Blocks

ACF Blocks don’t include styles by default. You should:

Add frontend CSS

Optionally add editor-only styles

Best practice is to namespace your styles:


.testimonial-block { 
	padding: 30px; 
	border-left: 4px solid #005af0; 
}

This prevents conflicts with other blocks or themes.

Using Block Settings and Attributes :

ACF Blocks support additional features:

Alignment options (alignwide, alignfull)

Custom anchors

Background colors

Custom class names

These options give editors flexibility while preserving layout consistency.

When Should You Use ACF Blocks?

ACF Blocks are ideal when:

You want structured content instead of free-form text

Editors need simple fields instead of complex layouts

Your design requires strict consistency

You prefer PHP over JavaScript-heavy development

They may not be ideal for:

Highly interactive blocks with animations

Blocks requiring real-time JavaScript logic

Best Practices for ACF Block Development

1. Keep block templates small and reusable
2. Use meaningful field names
3. Escape output for security
4. Avoid heavy queries inside blocks
5. Reuse styles across similar blocks
6. Test blocks with real content

Following these practices ensures long-term maintainability.

Build powerful ACF blocks with Gutenberg

The Way Forward

ACF Blocks bridge the gap between Gutenberg’s modern editing experience and traditional PHP-based WordPress development. They offer a powerful, flexible, and developer-friendly way to create custom blocks that are easy to edit, visually consistent, and scalable for large projects.

By leveraging ACF fields and PHP render templates, you can build professional-grade blocks without the complexity of JavaScript-heavy solutions. Whether you’re developing a custom theme, building client-specific components, or streamlining content workflows, ACF Blocks provide a reliable and efficient approach to modern WordPress block development.

Mastering ACF Blocks not only speeds up development—it empowers you to create structured, user-friendly editing experiences that truly shine.