ACF Blocks with block.json

Last updated Apr 20, 2023

Overview

Since ACF 6.0, ACF Blocks are registered by using the standard native WordPress function, register_block_type() which loads a block.json file containing all your configuration.

ACF hooks into block.json by reading the acf key in the JSON which should be an object of ACF specific configuration.

The main configuration keys for block.json are described in the WordPress documentation, but our specific ACF configuration is detailed below.

For further details, and a full example block, see What’s new with ACF Blocks in ACF 6

blocks/testimonial/block.json

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

ACF configuration key

(object) (Required) An Object containing ACF specific block configuration.

  • mode
    (String) (Optional) The display mode for your block. Available settings are “auto”, “preview” and “edit”. Defaults to “preview”. auto: Preview is shown by default but changes to edit form when block is selected. preview: Preview is always shown. The edit form will appear in the sidebar when the block is selected. edit: Edit form is always shown.

    Note. When in “preview” or “edit” modes, an icon will appear in the block toolbar to toggle between modes. 
    "mode" => "auto",

  • renderTemplate
    (String) The path to a template file used to render the block HTML. This can either be a relative path to a file based on where your block.json file is located, or an absolute path.

    "renderTemplate": "template-parts/blocks/testimonial/testimonial.php",

  • renderCallback
    (String) (Optional) Instead of providing a render_template, a callback function name may be specified to output the block’s HTML.

    // Specifying a function
"renderCallback": "my_acf_block_render_callback",

  • postTypes
    (Array) (Optional) An array of post types to restrict this block type to.

    "postTypes": ["post", "page"]

  • blockVersion
    (Integer) (Optional) The ACF block version this block should use. Defaults to 2

    "blockVersion": 2