ACF Blocks Configuration via block.json

Documentation ACF Blocks ACF Blocks Configuration via block.json

Last updated Dec 3, 2025

Description

Since ACF 6.0, ACF has recommended using block.json to handle your block registration.

A mirror of the WordPress JSON Schema for block.json, with ACF’s additions, is available at https://github.com/AdvancedCustomFields/schemas/blob/main/json/block.json.

The WordPress documentation for block.json, describing all the core properties, is available here.

If your block.json contains an ACF key, it will be loaded by ACF as an ACF Block.

Block.json ACF Key

The ACF key supports the following properties:

• renderTemplate
  (String) The path to a template file used to render the block HTML. This can either be a relative path from the block.json file or a full path to any file.

  // Specifying a relative path to the block.json file
  "acf": {
  "renderTemplate": "testimonial.php"
  }
  

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

  // Specifying a function
  "acf": {
  "renderCallback": "my_acf_block_render_callback"
  }
  

• 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. Edit form appears in sidebar when 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.

  "acf": {
  "mode": "auto"
  }
  

• blockVersion
  (Integer) The version of ACF Blocks to use. Version 1 of ACF Blocks is deprecated and not recommended for use with block.json. Default is 2.

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

  "acf": {
  "postTypes": ["post", "page"]
  }
  

• validate (Boolean) (Since 6.3.0) Should the fields in the block be validated as per the field group configuration. Default is true.

  "acf": {
  "validate": false
  }
  

• usePostMeta (Boolean) (Since 6.3.0) Should this block store its field values directly in post meta, rather than the block comment. When enabled, this block will be limited to once per page, and only as a top level block. These blocks will also not be supported as widgets or in the site editor/templates. Default is false.

  "acf": {
  "usePostMeta": true
  }
  

• hideFieldsInSidebar (Boolean) (Since 6.6.2) Whether to hide ACF fields from the block editor sidebar and only show them in the Expanded Editing Panel (v3 blocks only). Default is false.

  "acf": {
  "hideFieldsInSidebar": true
  }
  

• autoInlineEditing (Boolean) (Since 6.7) Enables automatic inline editing for fields within an ACF Block. When set to true, ACF will automatically apply inline editing functionality to any HTML elements where an ACF field’s value is the only content within that element (v3 blocks only). Default is false.

  "acf": {
  "autoInlineEditing": true
  }
  

Block.json Example

{
    "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",
        "validate": "false"
    },
    "supports": {
        "anchor": true
    }
}

Related

• Functions: acf_register_block_type()
• ACF Blocks: ACF Blocks V3
• ACF Blocks: How To Upgrade a Legacy Block to block.json With ACF 6
• ACF Blocks: Extending ACF Blocks With Block Supports
• ACF Blocks: ACF Blocks