Using ACF with the WordPress Block Bindings API

Occasionally, you may find yourself in a situation where you want to display some data you’ve stored inside of a custom field within the block editor in a paragraph or heading or similar.

Let’s say you have an book custom post type and a custom field that stores the ISBN for the book. You want to display that ISBN in the content within a paragraph. The ISBN number should dynamically change to whatever is stored in that custom field. How can you link the two so this occurs?

You can do this with the block bindings API introduced in WordPress 6.5. What you are binding to a block is a custom field. You’re linking the two together to say this content is tied to this custom field.

Let’s break it down.

The Set Up

To get started, your process doesn’t really change for setting up the ACF field with this data. You’re going to create a field group with a text field and assign that field group to the book custom post type. This is no different than you would do if you were displaying the field using a the_field call or similar within a template so far.

Binding the Block

Binding a block does not have a user interface yet so you have to actually get inside the code editor within the block editor to set up a bound block. You can access the code editor by going to the three vertical dots in the upper right and clicking it to swap to the code editor view.

Once in the code editor view, you would put the following to create a paragraph block linked to an ACF field called isbn.

<!-- wp:paragraph {
  "metadata":{
    "bindings":{
      "content":{
        "source":"acf/field",
        "args":{
          "key":"isbn"
        }
      }
    }
  }
} -->
<p>This will be replaced with the ISBN field on render</p>
<!-- /wp:paragraph -->

Notice “acf/field” is the metadata bindings source, as we’re using an ACF field. In the arguments, the key is the name of the field. If you called your field something other than isbn, you’d put whatever you called the field here instead.

So what you should have now is a custom post type with a populated ISBN custom field and a paragraph block within your block editor that shows the temporary value and shows a purple icon showing it is a bound block.

When you view the page on the front-end the paragraph is replaced with the value from the custom field.

Simplifying Block Binding with a Block Variation

Now, never in a million years would you tell a client to follow this process. Can you imagine? “Just pop into the code editor and bind the data with this code snippet.” Not happening.

So it would be advisable to simplify this process down by creating a block variation for a core paragraph that has this bound value baked into it so that a client can just add something like a “Book ISBN” block and it will get them where they want to go.

Here is an example of a block variation registered for a paragraph block bound to an ACF field value.

<?php
/**
 * Register book block type variations.
 *
 * @param array    $variations Array of block type variations.
 * @param WP_Block $block_type  The block type.
 * @return array
 */
function prefix_custom_book_block_type_variations( $variations, $block_type ) {

  if ( 'core/paragraph' === $block_type->name ) {
    $variations[] = array(
      'name'       => 'book-isbn',
      'title'      => 'Book ISBN',
      'attributes' => array(
        'placeholder' => 'This will be replaced with the ISBN field on render',
        'metadata' => array(
          'bindings' => array(
            'content' => array(
              'source' => 'acf/field',
              'args'   => array(
                'key' => 'isbn',
              ),
            ),
          ),
        ),
      ),
    );
  } 
  return $variations;

}
add_filter( 'get_block_type_variations', 'prefix_custom_book_block_type_variations', 10, 2 );

This will give the client a “Book ISBN” block variation that can be inserted with the binding to the ISBN custom field already baked in.

Looking to the Future

Not at all surprising there are some changes ahead for block bindings. In WordPress 6.6, block bindings will be displayed in the block inspector so it’ll be easier to see where data is coming from. Editing capabilities are also being added, where you can adjust the value directly from the block. You can read more about those upcoming changes for block bindings over on the WP dev blog. With how frequently things evolve with the block editor, the WP developer blog is an awesome resource to stay up to speed. Justin Tadlock also did a great walkthrough on block bindings, which you should definitely check out if you want to understand block bindings better.

Updated 8/18/24: Gutenberg 19.0 has an experimental UI for creating block bindings. To use it, you do need to install the Gutenberg plugin but you can read more about it over on the WP dev blog and play around with the possibilities there.