Key Concepts

Last updated Sep 27, 2023


ACF Blocks allows you to build on top of the WordPress blocks system introduced in WordPress 5.0 “Bebo”, giving you access to many of the same features available to core blocks, but with the output rendered from a PHP template. ACF Blocks are highly flexible, allowing you to define attributes, block styles, and block variations. You can then compose your ACF Blocks into patterns, templates and template parts, save them as synced patterns, and extend them to incorporate WordPress styles.

A thorough understanding of the Block Editor Handbook will greatly expand what you can build with ACF Blocks, but you don’t have to read the whole thing to get started. Below we highlight some of the key points to remember when working with blocks.

Key Terminology

Here are some common terms we’ll use to help distinguish between WordPress core block APIs and ACF Blocks APIs when necessary:

  • ACF Block(s): Represents the ACF product’s API extensions, which mostly leverage and are scaffolded on top of WordPress core block’s APIs.
  • WordPress core block(s): Refers to WordPress’s native and core APIs for blocks, which most of ACF Blocks is built upon. WordPress core blocks are mostly written in React.
  • Block(s) or block(s): When used without the prefix “ACF” or “WordPress core”, this refers to the general concept and lower-level APIs used by both WordPress core blocks and ACF Blocks, as well as the end output from the block.

Points to Remember

  • Block data is saved within the post_content database table as serialized HTML. This makes them unique to meta boxes that save data to the postmeta table.
  • Every block in WordPress requires a block.json file to register its properties. This is the entry point for every new block type.
  • Native WordPress blocks can be static or dynamic. ACF Blocks are a custom type of dynamic block, rendered by ACF on the server and allowing for PHP logic.

Elements of ACF Blocks

There are three essential elements when it comes to ACF Blocks: a block.json file, a PHP file, and a CSS file. In fact, the CSS file is optional as your block may inherit styles from your theme, but you’ll need it to incorporate any unique styling. Most ACF Blocks also have an ACF field group associated with them, allowing the ACF Block to pull data from the fields. However, this is not actually essential to creating an ACF Block.

ACF Blocks and block.json

Both WordPress core blocks and ACF Blocks register their properties in a file called block.json. We go deeper into this in Create Your First ACF Block, but the central point of block.json is that it defines your block settings, styles, and metadata.

The configuration keys used in ACF Blocks are largely the same as the ones used in WordPress core blocks, including the use of camelCase. The primary difference is the addition of the acf configuration key.

    "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"
  • mode (string) (optional) The display mode for your block. Available settings are “auto”, “preview” and “edit”. Defaults to “preview”. Note: When in “preview” or “edit” modes, an icon will appear in the block toolbar to toggle between modes, unless you also add mode: false to a root level supports key.
    • 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, unless you also add mode: false to a root level supports key.

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

  • 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",

Block Variables (or Parameters for Callbacks) in PHP

You have access to data about your block by default when creating an ACF Block, either by variables made available in your template or passed into your callback as parameters. New parameters are defined in exactly the same way as any other PHP template file.

  • $block (array) The block settings and attributes.
  • $content (string) The block inner HTML (empty).
  • $is_preview (boolean) True during backend preview render.
  • $is_preview (boolean) True during backend preview render, i.e., when rendering inside the block editor’s content, or rendered inside the block editor when adding a new block, showing a preview when hovering over the new block. This variable is only set to true when is_admin() and current screen is_block_editor() both return true.
  • $context (array) The context provided to the block by the post or its parent block.

Next: Create Your First ACF Block