Introducing Block Bindings, part 1: connecting custom fields

Looking over the laundry list of developer-specific features coming in WordPress 6.5, I’m like a kid on Christmas morning, shredding the wrapping paper to reveal all the goodies Santa dropped off the night before. But there’s that one special gift. The big one. The one I’ve been wishing and hoping for.

It’s the Block Bindings API.

For extenders, this is the foundation of so many features we’ve all been asking for since the launch of WordPress 5.0 and the Block Editor. This initial iteration provides support for custom fields integration, pattern overrides, and custom bindings.

This post is the start of an in-depth series that covers what block bindings are, why you should use them, and how to use them in your projects. In this first post, you’ll learn how to bind custom fields to block attributes.

I encourage you to leave comments on what you’d like to build with the Block Bindings API. What you see in WordPress 6.5 is only the first iteration of a massively powerful feature that will only become better in the versions to come. 

What are block bindings?

Before we dive into the really fun stuff like connecting custom fields, let’s set the groundwork. It’s important to understand what the Block Bindings API is and why it’s so vital to the future of WordPress.

The basic structure of a block and bindings

Take a look at the markup for a basic Image block:

<!-- wp:image -->
<figure class="wp-block-image"><img src="" alt=""/></figure>
<!-- /wp:image -->

What the Block Bindings API does is let you “bind” dynamic data to the block’s attributes, which are then reflected in the final HTML markup that is output to the browser on the front end.

This means you can do things like bind a custom URL to the Image block’s url attribute and text to the alt attribute with data from custom fields (post meta), site data, and even more.

It’s also necessary to understand what attributes are available for a block that you want to bind data to. For the Image block, you can view its attributes via its block.json file. There are many potential attributes. But for this exercise, let’s focus only on url and alt:

{
	"attributes": {
		"url": {
			"type": "string",
			"source": "attribute",
			"selector": "img",
			"attribute": "src",
			"__experimentalRole": "content"
		},
		"alt": {
			"type": "string",
			"source": "attribute",
			"selector": "img",
			"attribute": "alt",
			"default": "",
			"__experimentalRole": "content"
		}
	}
}

If you look closely at the block markup and compare it to the attributes property in block.json, you’ll see:

• The url block attribute maps to <img src=""/>.
• Likewise, the alt block attribute maps to <img alt=""/>.

In a real-world scenario, the Image block markup would look more like this (formatted for clarity):

<!-- wp:image {
	"lightbox":{"enabled":true},
	"id":1,
	"sizeSlug":"large",
	"linkDestination":"none"
} -->
<figure class="wp-block-image size-large">
	<img src="/path/to/image.jpg" alt="This is the image alt text" class="wp-image-1"/>
</figure>
<!-- /wp:image -->

This markup indicates that:

• The url block attribute is /path/to/image.jpg.
• The alt block attribute is This is the image alt text.

It’s important to grasp the relationship between block attributes and how they are represented in the markup because the Block Bindings API works entirely with the attributes system.

Why the Block Bindings API is useful

What makes Bindings so powerful is that you can bind dynamic data to block attributes. Before WordPress 6.5, adding dynamic data within the block system meant building a custom dynamic block.

Let’s take a look at a real-world example. If you open the Your Name movie page from the WP Movies Demo, you will see a lot of data that has been generated dynamically: