ACF Blocks Configuration via block.json

---

• Description
• Block.json ACF Key
• Block.json Example

---

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"
  }
  

  Note (v3 blocks):** Setting "mode": "edit" combined with "supports": { "mode": false } is the legacy v2 way to disable the editor preview. When ACF detects both settings on a v3 block, it automatically treats them as renderPreview: false. The recommended approach for new v3 blocks is to use acf.renderPreview: false directly.

• 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
  }
  

  renderPreview (Boolean) (Since 6.x) Whether to render a live preview of the block in the editor. When set to false, a placeholder showing the block icon, title, and an Edit Block button is shown instead. The block’s render template continues to run normally on the front-end. Default is true (v3 blocks only).

  "acf": {
  "renderPreview": false
  }
  

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
    }
}