Skip To Main Content

How to use ACF Blocks (with ACF Pro)

ACF Blocks is a premium feature of ACF Pro that allows developers to build custom block types without the thorough knowledge of JavaScript or React required to create WordPress blocks.

When using WPGraphQL Content Blocks v1.2.0+ and wpgraphql-acf v2.0.0, you can query the blocks as GraphQL Types! This how-to guide will show you the steps needed to perform that successfully.

Installing the plugins

Make sure you install the required plugins first:

Let’s get started with registering our own block with ACF.

Registering ACF Blocks

You can register ACF Blocks using code or using ACF Extended’s Block Types UI (a separate third-party plugin).

We created a Testimonial block using the @wordpress/create-block package.
Here is the associated block.json:

    "name": "acf/testimonial",
    "title": "Testimonial",
    "description": "A custom testimonial block that uses ACF fields.",
    "style": [ "file:./testimonial.css" ],
    "category": "formatting",
    "icon": "admin-comments",
    "keywords": ["testimonial", "quote"],
    "acf": {
        "mode": "preview",
        "renderTemplate": "testimonial.php"
    "supports": {
        "anchor": true

Code language: JSON / JSON with Comments (json)

This contains the custom acf property containing the ACF block fields that ACF needs to register the block.

The testimonial.php contains the HTML markup of the testimonial block:

 * Testimonial Block template.
 * @param array $block The block settings and attributes.

// Load values and assign defaults.
$quote             = !empty(get_field( 'quote' )) ? get_field( 'quote' ) : 'Your quote here...';
$quote_attribution = '';

// Create class attribute allowing for custom "className" and "align" values.
$class_name = 'testimonial';

// Build a valid style attribute for background and text colors.
$styles = array( );

<div class="<?php echo esc_attr( $class_name ); ?>" style="">
    <div class="testimonial__col">
        <blockquote class="testimonial__blockquote">
            <?php echo esc_html( $quote ); ?>

Code language: HTML, XML (xml)

Adding ACF Field Groups to ACF Blocks

ACF Pro allows ACF Field Groups to be assigned to ACF Blocks as a location.

After you’ve assigned an ACF Field Group to an ACF Block, that field group can be accessed from the block.

We create a new ACF Field and assign the Testimonial block to that field using the Location Rules Tab. Then we Create a new Field for the quote attribute.

Adding ACF Field Groups to ACF Blocks.

See the Block in the GraphQL Schema

Next, you should be able to see the Block and the ACF Field Group associated with the block in the GraphQL Schema.

Inspecting the Block in the GraphQL Schema.

Use the Block in Content

Next, you can use the block in your content.

Using the block in your content.

Query for the Block

Now you can query for EditorBlocks, and specify fields you want for your specific ACF Blocks.

Query for the ACF Block in GraphQL UI.