ACF Blocks V3

Documentation ACF Blocks ACF Blocks V3

Last updated Oct 7, 2025

ACF Blocks V3

ACF Blocks Version 3 brings your ACF Blocks improved usability, new functionality, and fixes some issues as well:

• New: ACF Blocks v3 is compatible with WordPress/Gutenberg blocks v3 (iframe)
• New: ACF Blocks Edit Mode has been removed and replaced with a slide-out sidebar/modal. The preview area is always the preview area, and fields can be edited either in the sidebar, or in the larger slide-out/modal sidebar
• Fixed: You can now edit ACF blocks in Edit mode inside WP Core’s pattern editor
• Fixed/Changed: Validation errors now first appear after you click “Save/publish”, as opposed to immediately, while you are typing into a field for the first time
• Fixed/Changed: After fixing a field validation error it shows as fixed immediately as opposed to needing to click out of the block and back into it
• Fixed: Blocks with radio buttons no longer affect each other’s field values
• Fixed: Blocks with required radio buttons now validate correctly
• Fixed: ACF field validation now works in the Site Editor
• Fixed: WYSIWYG fields are no longer affected by typing into other blocks

Upgrading to v3

To upgrade your blocks to version 3, you have a few options depending on your needs.

If using block.json

If you are using block.json to register your blocks, you can add a blockVersion key to the acf object, and set its value to 3. For example:

{
"name": "acf/my-block",
"title": "My Block",
"acf": { 
   "blockVersion": 3,
   "renderTemplate": "render-template.php"
 },
}

If using acf_register_block_type

If you are using the acf_register_block_type PHP function to register your blocks, add the acf_block_version to it. For example:

function my_acf_blocks_init() {
    acf_register_block_type(
        array(
            'name' => 'testimonial',
            'title' => 'Testimonial',
            'render_template' => 'blocks/testimonial-block.php'
            'api_version' => 3,
            'acf_block_version' => 3,
        )
    );
}
add_action('acf/init', 'my_acf_blocks_init');

If you want to opt-in all of your blocks in a single line

If you want to opt all of your blocks into version 3 you can use the acf/blocks/default_block_version PHP filter, which will make any blocks without a specific version defined use version 3. For example:

function my_custom_function_to_bump_the_block_version( $version, $block ) {
     return 3;
}
add_filter( 'acf/blocks/default_block_version', 'my_custom_function_to_bump_the_block_version', 10, 2 );

Note that if you have defined the blockVersion specifically in your block.json file, the acf/blocks/default_block_version filter will not override that.

Notable changes from V2

In ACF Blocks Version 2, you could have your fields show up in the preview area by using “Edit” mode, or you could have them show up in the block editor sidebar if your block is in “Preview” mode. You could also toggle between the two by clicking the pencil icon in the block’s toolbar.

But in ACF Blocks Version 3, the concept of modes no longer exists. Rather, your block will always be in “preview”, always showing what’s in your PHP render template in the block preview area.

The block’s ACF fields show up in the sidebar, and also in a pop-out sidebar that has more space.

The pencil icon button in the block toolbar remains, and when clicked it will open the fields in the larger pop-out sidebar, allowing you to have more space for editing your fields.

ACF Blocks Version 3 is available from ACF PRO version 6.6 or later.

Related

• Functions: acf_register_block_type()
• ACF Blocks: How To Upgrade a Legacy Block to block.json With ACF 6
• ACF Blocks: ACF Blocks Configuration via block.json
• ACF Blocks: What’s New With ACF Blocks in ACF 6
• ACF Blocks: ACF Blocks