Block Bindings API Explained

February 4, 2025

I noticed that there is not so much interest in the Block Bindings API, comparing, for example, to the Interactivity API.

However, the Block Bindings API is quite interesting indeed because it allows us to connect a Gutenberg block attribute value to a custom field or pretty much any other custom source (it even could be a REST API response from a completely other site).

In this tutorial, I will show you a couple of examples of the Block Bindings API in action.

Block Bindings Examples

I think it is always a good idea to start with examples. Below, I am going to show you three of them:

in the first one, we will connect (bind) a custom field value to the “Paragraph” block content,
in the second example, I will show you how to create a custom source in PHP,
finally, we will learn how to pass arguments to your custom source and process them.

Let’s get started!

1. Using a custom field as a binding source

Let’s assume, that we have a paragraph block and we want its text to be replaced automatically with a value of a specific custom field.

The only requirement here is that your custom field should be registered in the REST API.

Take a look at this screenshot:

Block bindings custom field example — Of course, it is not necessary to display the “Custom Fields” section in the Block Editor. I displayed it for you just to show that the custom field value is used as a paragraph block text.

To achieve that we need to switch the editor from “Visual” to “Code” mode here:

How to switch to the code editor in Gutenberg

And then to add the block binding like this into the block markup:

<!-- wp:paragraph {
	"metadata":{
		"bindings":{
			"content":{
				"source":"core/post-meta",
				"args":{"key":"misha_custom_field"}
			}
		}
	}
} -->
<p></p>
<!-- /wp:paragraph -->

In this code you can see, that we’re adding a parameter to the metadata – bindings, where we say that the content should be taken from the custom fields and we need to use a value from the misha_custom_field custom field for that.

Great, now we have created a basic block binding. The paragraph block text is now not editable and it takes the value from the custom field.

2. Using a custom binding source

Custom field values are not the only thing you can use for the block bindings. So, let’s just continue to work with our paragraph block, and let’s use a custom source for it, not just a custom field value but a custom PHP function.

The good news for you guys is that we don’t even need to write any JavaScript code here, we can create a custom source easily with the PHP function register_block_bindings_source().

For example, let’s say, that instead of a custom field value we need to print a current year dynamically (it is going to be kind of a copyright block). Below is the code you can use to achieve that:

// we're going to use the function inside of init hook
add_action( 'init', function() {

	register_block_bindings_source( 
		'misha/copyright', // we're going to use it as a source name later
		array(
			'label' => 'Copyright', // displayed in the Block Editor
			'get_value_callback' => 'rudr_copyright_binding',
		)
	);

} );

function rudr_copyright_binding() {
	return '&copy; ' . date( 'Y' );
}

Then, let’s make the appropriate changes in the paragraph block markup:

<!-- wp:paragraph {
	"metadata":{
		"bindings":{
			"content":{
				"source":"misha/copyright"
			}
		}
	}
} -->
<p></p>
<!-- /wp:paragraph -->

Here we go:

3. Using a custom binding source with parameters

You can pass any custom parameters into your custom source the same way we passed a custom field key when we were using core/post-meta as a source, in the first example.

Plus, let’s make everything much more interesting by using an “Image” block instead of a “Paragraph” block because in the latter one, you can only bind the content of the block, but in the image block, you can bind: the image URL, alternative text and title.

Let’s take a look at the block markup first:

<!-- wp:image {
	"metadata":{
		"bindings":{
			"url":{
				"source":"misha/image",
				"args":{"filename":"elf.jpg"}
			}, 
			"alt":{
				"source":"misha/image"
			}
		}
	}
} -->
<figure class="wp-block-image"><img alt=""/></figure>
<!-- /wp:image -->

We can provide different sources for every image attribute, however, as you can see, I am using the same source name for both url and alt block attributes, which means that we need to separate them somehow in the callback function below and we’re going to do it with a condition using the $attribute_name argument of the callback function.

add_action( 'init', function() {

	register_block_bindings_source( 
		'misha/image',
		array(
			'label' => 'Custom image source',
			'get_value_callback' => 'rudr_image_binding',
		)
	);

} );

function rudr_image_binding( $source_args, $block_instance, $attribute_name ) {
	
	if( 'url' === $attribute_name ) {
		if( ! empty( $source_args[ 'filename' ] ) ) {
			return site_url( "images/{$source_args[ 'filename' ]}" );
		} else {
			return site_url( 'images/example.jpg' );	
		}
	}
	
	if( 'alt' === $attribute_name ) {
		return 'Some custom alternative text for our image.';
	}

}

If you’re using the same source for different blocks, you can use a condition like this in your callback function:

if( 'core/image' === $block_instance->parsed_block[ 'blockName' ] ) {
	
}

The List of Supported Blocks

Below, you can find the list of standard WordPress blocks and their attributes that support the Block Bindings API.

Block name	Supported attributes
Paragraph	`content`
Image	`url`, `alt`, `title`
Heading	`content`
Button	`url`, `text`, `linkTarget`, `rel`

What about custom blocks? But why do you ever need a binding in a custom block since you can already add anything you want into it?

Block Bindings in The Block Editor Interface

You might be thinking at the moment – so what, should we always switch to the “Code editor” and create block bindings there? No, absolutely not.

Though you can find mentions on some websites that there is no UI for binding attributes to custom fields, this information is already outdated. Yes, there is and it has been, since WordPress 6.6.

And below I will uncover the ways how you can manage block bindings within the block editor interface.

Attributes section

First things first, you can go to the block settings and find the “Attributes” section.

However, this section only shows the list of custom fields available for the block bindings. It means, that you won’t find your custom binding sources there.

Creating a block variation

If you’re working with clients and you need them to use block bindings, believe me, you’ll make them pissed off pretty quickly if you try to make them work with the “Attributes” section or even with the block markup.

A nice solution here – block variations.

Basically, you just create a block variation with all the necessary block bindings and here you go, we can say, that you have a brand new block now:

Registering a block variation for a block binding. — It is a block binding with a custom source we created above.

Probably, it would be better to publish a separate tutorial about block variations as well, but for now, we’re just going to use a simple PHP hook – get_block_type_variations.

add_filter( 'get_block_type_variations', function( $variations, $block_type ) {

	// do nothing if it is not a paragraph block
	if( 'core/paragraph' !== $block_type->name ) {
		return $variations;
	}
	
	// add a block variation here
	$variations[] = array(
		'name' => 'misha-copyright',
		'title' => 'Copyright',
		'description' => 'Displays the copyright sign along with the current year',
		'keywords' => array( 'copyright' ),
		'isDefault' => false,
		'icon' => 'info', // from Dashicons set
		'attributes' => array(
			'metadata' => array(
				// here they are, the block bindings
				'bindings' => array(
					'content' => array(
						'source' => 'misha/copyright',
					),
				),
			),
		),
	);

	return $variations;

}, 25, 2 );

I think that’s pretty much it – the bare minimum to start learning the Block Bindings API. If you have any questions, welcome to the comments section below.

# Gutenberg, WordPress