register_block_bindings_source() │ WP 6.5.0

Registers a new data source for blocks, allowing dynamic substitution of values in block attributes during their rendering.

The custom data source is linked to block attributes through the Block Bindings API. This allows values from arbitrary fields, external APIs, or other sources to be substituted without the need to create new blocks.

The registration of the source consists of defining a "name" for the source and a "callback function" that defines how to obtain the value from the source and pass it to the block attribute.

After registering the source, any block that supports the bindings API can use its value by specifying it in the attribute metadata.bindings.

No Hooks.

Returns

WP_Block_Bindings_Source|false.

• WP_Block_Bindings_Source — on successful registration.
• false — in case of an error.

Usage

register_block_bindings_source( $source_name, $source_properties );

$source_name(string) (required)

Unique name of the source in the format namespace/slug. It should contain only lowercase letters, digits, hyphens, and slashes.
For example my-plugin/my-custom-source.

$source_properties(array) (required)

Array of parameters for registering the source:

• label(string)
  Name of the source.

• get_value_callback(callable)
  Callback function called when obtaining the value from the source (during block rendering).

  Callback function signature:

  function( array $args, WP_Block $block, string $attr_name ): mixed

  • $args(array)
    Array of arguments specified in the block (during binding). These are the data specified in the block's JSON data in the args parameter during binding (see example below). For example:

    // in the block's json data:
    "metadata": {
    	"bindings": {
    		"content": {
    			"source": "my-plugin/my-custom-source",
    			"args": {
    				"key": "custom_field_key"
    			}
    		}
    	}
    }
    // the function parameter will receive the array:
    [ 'key' => 'custom_field' ]

  • $block(WP_Block)
    Object of the current block. Through it, you can obtain context (for example postId), attributes, and other information about the block.

  • $attr_name(string)
    Name of the block attribute to which the binding is applied. For example, content for a paragraph, or url for an image. This allows one function to handle multiple attributes if needed.

  The callback can return different values:

  • string to override the original value of the block
  • null
  • false to remove the attribute
    and so on.

• uses_context(array of strings) (optional)
  Array of block contexts required for the source, for example: ['postId'].

  Indicates which block contexts the data source needs to work correctly.

  This is information that the block receives from the environment. For example, the current post ID (postId), template ID (templateId), post type (postType), etc.

  If the source depends on such data (for example, to obtain the meta-field of the current post), it is necessary to explicitly specify which contexts it requires. Then WordPress will automatically pass them to $block->context.

  Example:

  'uses_context' => [ 'postId' ]

  This means that the source requires the ID of the current post, and this ID can be obtained as follows:

  $post_id = $block->context['postId'];

  Without uses_context, the required context will not be passed to the block, and it will not be possible to obtain, for example, postId.

Examples

add_action( 'init', 'my_plugin_register_block_bindings_sources' );
function my_plugin_register_block_bindings_sources() {
	register_block_bindings_source(
		'my-plugin/my-custom-source', [
			'label'              => 'My Custom Source',
			'get_value_callback' => 'my_plugin_get_custom_source_value',
			'uses_context'       => [ 'postId' ],
		]
	);
}

function my_plugin_get_custom_source_value( array $args, WP_Block $block, string $attr_name ) {
	$post_id = $block->context['postId'];
	$meta_key = $args['meta_key'] ?? '';

	return get_post_meta( $post_id, $meta_key, true );
}

<!-- wp:paragraph {
	"metadata": {
		"bindings": {
			"content": {
				"source": "my-plugin/my-custom-source",
				"args": {
					"meta_key": "custom_field_key"
				}
			}
		}
	}
} -->
<p>Default value (will be replaced)</p>
<!-- /wp:paragraph -->

add_action( 'init', 'register_external_data_source' );
function register_external_data_source() {
	register_block_bindings_source( 'my-plugin/external-data', [
		'label'              => 'External Data',
		'get_value_callback' => 'get_external_data',
	] );
}

function get_external_data( array $args, WP_Block $block, string $attr_name ) {
	$response = wp_remote_get( 'https://api.example.com/data' );
	if ( is_wp_error( $response ) ) {
		return 'Error retrieving data';
	}

	$data = json_decode( wp_remote_retrieve_body( $response ), true );

	return $data['value'] ?? 'Data not available';
}

<!-- wp:image {
	"id": 123,
	"sizeSlug": "large",
	"linkDestination": "none",
	"metadata": {
		"bindings": {
			"alt": {
				"source": "my-plugin/external-data"
			}
		}
	}
} /-->

add_filter( 'block_bindings_source_value', 'format_custom_value', 10, 5 );

/**
 * @param mixed    $value          The computed value for the source.
 * @param string   $name           The name of the source.
 * @param array    $source_args    Array containing source arguments used to look up the override value, i.e. { "key": "foo" }.
 * @param WP_Block $block_instance The block instance.
 * @param string   $attribute_name The name of an attribute.
 *
 * @return mixed
 */
function format_custom_value( $value, $name, $source_args, $block_instance, $attribute_name ) {
	if ( $name === 'my-plugin/custom-source' && is_string( $value ) ) {
		return strtoupper( $value );
	}

	return $value;
}

Add Your Own Example