The Block Bindings API lets 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.

An example could be connecting an Image block url attribute to a function that returns random images from an external API.

<!-- wp:image {
    "metadata":{
        "bindings":{
            "url":{
                "source":"my-plugin/get-random-images"
            }
        }
    }
} -->

Compatible blocks and their attributes

Right now, not all block attributes are compatible with block bindings. There is some ongoing effort to increase this compatibility, but for now, this is the default list:

Core Sources

WordPress includes several built-in block bindings sources that you can use without any custom registration:

• core/post-meta
• core/post-data
• core/term-data
• core/pattern-overrides

core/post-meta

The core/post-meta source allows you to bind block attributes to post meta fields.

Requirements:

• Post meta must be registered with show_in_rest => true
• Post meta keys cannot start with an underscore (protected keys are not accessible)

Example usage:

First, register your post meta:

register_meta(
    'post',
    'my_custom_field',
    array(
        'show_in_rest' => true,
        'single'       => true,
        'type'         => 'string',
    )
);

Then bind it to a block attribute:

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

core/post-data

Note: Since WordPress 6.9.

The core/post-data source provides access to post data fields.

Available fields:

• date – The post publication date
• modified – The post last modified date
• link – The post permalink

Example usage:

<!-- wp:paragraph {
    "metadata":{
        "bindings":{
            "content":{
                "source":"core/post-data",
                "args":{"field":"date"}
            }
        }
    }
} -->
<p>Fallback content</p>
<!-- /wp:paragraph -->

core/term-data

Note: Since WordPress 6.9.

The core/term-data source provides access to taxonomy term data fields when term context is available. It requires termId and taxonomy to be available from block context to function properly.

Available Fields

Example Usage

Display term names in a list:

<!-- wp:terms-query {"termQuery":{"taxonomy":"category","perPage":5}} -->
<div class="wp-block-terms-query">
    <!-- wp:term-template {"layout":{"type":"default"}} -->
    <!-- wp:paragraph {"metadata":{"bindings":{"content":{"source":"core/term-data","args":{"field":"name"}}}}} -->
    <p>Category Name</p>
    <!-- /wp:paragraph -->
    <!-- /wp:term-template -->
</div>
<!-- /wp:terms-query -->

Create linked term archives:

<!-- wp:terms-query {"termQuery":{"taxonomy":"post_tag","perPage":10}} -->
<div class="wp-block-terms-query">
    <!-- wp:term-template {"layout":{"type":"default"}} -->
    <!-- wp:paragraph {"metadata":{"bindings":{"content":{"source":"core/term-data","args":{"field":"name"}}}}} -->
    <p><a href="#">Tag Name</a></p>
    <!-- /wp:paragraph -->
    <!-- /wp:term-template -->
</div>
<!-- /wp:terms-query -->

Context Requirements

The core/term-data source works in these contexts:

1. Any block providing term context – Built-in blocks like core/term-template, or custom blocks that provide termId and taxonomy via block context
2. Navigation Blocks – Special backwards compatibility handling for core/navigation-link and core/navigation-submenu (these read from block attributes instead of context)

core/pattern-overrides

The core/pattern-overrides source enables pattern instances to have their content overridden on a per-instance basis. This is particularly useful for synced patterns where you want to allow specific blocks to be customized while keeping the rest of the pattern synchronized .

How it works:

• Pattern blocks can define which attributes are overridable using metadata.bindings
• Each pattern instance stores its override values in the content attribute
• The binding connects the block attribute to the override value using the block’s metadata.name as a key
• The context structure follows: pattern/overrides <span aria-hidden="true" class="wp-exclude-emoji">→</span> {block_name} <span aria-hidden="true" class="wp-exclude-emoji">→</span> {attribute_name}

Example usage:

In the pattern definition, mark blocks as overridable:

<!-- wp:paragraph {
   "metadata":{
      "bindings":{
         "content":{
            "source":"core/pattern-overrides"
         }
      },
      "name":"custom-heading"
   }
} -->
<p>Default heading text</p>
<!-- /wp:paragraph -->

When the pattern is instantiated, users can override the content for that specific instance:

<!-- wp:block {"ref":123,"content":{"custom-heading":{"content":"My custom heading text"}}} / -->

In this example:

• custom-heading is a unique identifier for the core/paragraph block within the core/pattern-overrides system.
• It acts as a key in the overrides context structure: pattern/overrides <span aria-hidden="true" class="wp-exclude-emoji">→</span> custom-heading <span aria-hidden="true" class="wp-exclude-emoji">→</span> content.
• This identifier allows multiple blocks of the same type (e.g., core/paragraph) within a pattern to have distinct, per-instance attribute overrides using metadata.name.

For instance, "custom-heading" links the specific paragraph block’s content attribute to its override value ("My custom heading text") for a particular pattern instance.

Extending supported attributes

Note: Since WordPress 6.9.

Developers can extend the list of supported attributes using the block_bindings_supported_attributes filter. This filter allows adding support for additional block attributes.

There are two filters available:

• block_bindings_supported_attributes: A general filter that receives the supported attributes array and the block type name.
• block_bindings_supported_attributes_{$block_type}: A dynamic filter specific to a block type (e.g., block_bindings_supported_attributes_core/image).

Example of adding support for the caption attribute on the Image block:

add_filter(
    'block_bindings_supported_attributes_core/image',
    function ( $supported_attributes ) {
        $supported_attributes[] = 'caption';
        return $supported_attributes;
    }
);

Example of adding support for a custom block:

add_filter(
    'block_bindings_supported_attributes_my-plugin/my-block',
    function ( $supported_attributes ) {
        $supported_attributes[] = 'title';
        $supported_attributes[] = 'description';
        return $supported_attributes;
    }
);

This filter also affects which blocks and attributes are available for Pattern Overrides, as both features share the same underlying supported attributes configuration.

Registering a custom source

Registering a source requires defining at least name, a label and a callback function that gets a value from the source and passes it back to a block attribute.

Once a source is registered, any supporting block’s metadata.bindings attribute can be configured to read a value from that source.

Registration can be done on the server via PHP or in the editor via JavaScript, and both can coexist.

The label defined in server registration will be overridden by the label defined in the editor.

Server registration

Server registration allows applying a callback that will be executed on the frontend for the bound attribute.

The function to register a custom source is register_block_bindings_source($name, $args):

• name: string that sets the unique ID for the custom source.
• args: array that contains:
  • label: string with the human-readable name of the custom source.
  • uses_context: array with the block context that is passed to the callback (optional).
  • get_value_callback: function that will run on the bound block’s render function. It accepts three arguments: source_args, block_instance and attribute_name. This value can be overridden with the filter block_bindings_source_value.

Note that register_block_bindings_source() should be called from a handler attached to the init hook.

Here is an example:

add_action(
    'init',
    function () {
        register_block_bindings_source(
            'wpmovies/visualization-date',
            array(
                'label'              => __( 'Visualization Date', 'custom-bindings' ),
                'get_value_callback' => function ( array $source_args, $block_instance ) {
                    $post_id = $block_instance->context['postId'];
                    if ( isset( $source_args['key'] ) ) {
                        return get_post_meta( $post_id, $source_args['key'], true );
                    }
                },
                'uses_context'       => array( 'postId' ),
            )
        );
    }
);

This example needs a post_meta registered, and, also, a filter can be used to return a default $visualization_date value, which will be shown in the next heading.

add_action(
    'init',
    function () {
        register_meta(
            'post',
            'wp_movies_visualization_date',
            array(
                'show_in_rest' => true,
                'single'       => true,
                'type'         => 'string',
                'label'        => __( 'Movie visualization date', 'custom-bindings' ),
            )
        );
    }
);

Block bindings source value filter

Note: Since WordPress 6.7.

The value returned by get_value_callback can be modified with the block_bindings_source_value filter.
The filter has the following parameters:

• value: The value to be filtered.
• name: The name of the source.
• source_args: array containing source arguments.
• block_instance: The block instance object.
• attribute_name: The name of the attribute.

Example:

function wpmovies_format_visualization_date( $value, $name ) {
    // Prevent the filter to be applied to other sources.
    if ( $name !== 'wpmovies/visualization-date' ) {
        return $value;
    }
    if ( ! $value ) {
        return date( 'm/d/Y' );
    }
    return date( 'm/d/Y', strtotime( $value ) );
}

add_filter( 'block_bindings_source_value', 'wpmovies_format_visualization_date', 10, 2 );

Server registration Core examples

There are a few examples in Core that can be used as reference.

• Post Meta. Source code
• Post Data. Source code
• Term Data. Source code
• Pattern overrides. Source code
• Twenty Twenty-Five theme. Source code

Editor registration

Note: Since WordPress 6.7.

Editor registration on the client allows defining what the bound block will do when the value is retrieved or when the value is edited.

The function to register a custom source is registerBlockBindingsSource( args ):

• args: object with the following structure:
  • name: string with the unique and machine-readable name.
  • label: string with the human readable name of the custom source. In case it was defined already on the server, the server label will be overridden by this one, in that case, it is not recommended to be defined here. (optional)
  • usesContext: array with the block context that the custom source may need. In case it was defined already on the server, it should not be defined here. (optional)
  • getValues: function that retrieves the values from the source. (optional)
  • setValues: function that allows updating the values connected to the source. (optional)
  • canUserEditValue: function to determine if the user can edit the value. The user won’t be able to edit by default. (optional)
  • getFieldsList: function that returns available fields for the UI dropdown selector. (Since WordPress 6.9) (optional)

This example will show a custom post meta date in the editor and, if it doesn’t exist, it will show today’s date. The user can edit the value of the date. (Caution: This example does not format the user input as a date—it’s only for educational purposes.)

import { registerBlockBindingsSource } from '@wordpress/blocks';
import { __ } from '@wordpress/i18n';
import { store as coreDataStore } from '@wordpress/core-data';

registerBlockBindingsSource( {
    name: 'wpmovies/visualization-date',
    label: __( 'Visualization Date', 'custom-bindings' ), // We can skip the label, as it was already defined in the server in the previous example.
    usesContext: [ 'postType' ], // We can skip postId, as it was already defined in the server in the previous example.
    getValues( { select, context } ) {
        let wpMoviesVisualizationDate;
        const { getEditedEntityRecord } = select( coreDataStore );
        if ( context?.postType && context?.postId ) {
            wpMoviesVisualizationDate = getEditedEntityRecord(
                'postType',
                context?.postType,
                context?.postId
            ).meta?.wp_movies_visualization_date;
        }
        if ( wpMoviesVisualizationDate ) {
            return {
                content: wpMoviesVisualizationDate,
            };
        }

        return {
            content: new Date().toLocaleDateString( 'en-US' ),
        };
    },
    setValues( { select, dispatch, context, bindings } ) {
        dispatch( coreDataStore ).editEntityRecord(
            'postType',
            context?.postType,
            context?.postId,
            {
                meta: {
                    wp_movies_visualization_date: bindings?.content?.newValue,
                },
            }
        );
    },
    canUserEditValue( { select, context } ) {
        return true;
    },
} );

getValues

The getValues function retrieves the value from the source on block loading. It receives an object as an argument with the following properties:

• bindings returns the bindings object of the specific source. It must have the attributes as a key, and the value can be a string or an object with arguments.
• clientId returns a string with the current block client ID.
• context returns an object of the current block context, defined in the usesContext property. More about block context..
• select returns an object of a given store’s selectors. More info in their docs..

The function must return an object with this structure:
{ 'block attribute' : value }

setValues

The setValues function updates all the values of the source of the block bound. It receives an object as an argument with the following properties:

• bindings returns the bindings object of the specific source. It must have the attributes as a key, and the value can be a string or an object with arguments. This object contains a newValue property with the user’s input.
• clientId returns a string with the current block client ID.
• context returns an object of the current block context, defined in the usesContext property. More about block context..
• dispatch returns an object of the store’s action creators. More about dispatch.
• select returns an object of a given store’s selectors. More info in their docs..

getFieldsList

Note: Since WordPress 6.9.

The getFieldsList function enables custom sources to appear in the Block Bindings UI dropdown selector. When a user selects an option from the dropdown, the source is automatically bound to the block attribute with the corresponding args from the selected field. This function must return an array of field objects that define the available binding options.

Each field object in the array should have the following properties:

• label: string that defines the label shown in the dropdown selector. Defaults to the source label if not provided.
• type: string that defines the attribute value type. It must match the attribute type it binds to; otherwise, it won’t appear in the UI. For example, an id attribute that accepts only numbers should only display fields that return numeric values.
• args: object that defines the source arguments that are applied when a user selects the field from the dropdown.

Example:

registerBlockBindingsSource( {
    name: 'my-plugin/custom-fields',
    label: 'Custom Fields',
    getFieldsList() {
        return [
            {
                label: 'Author Name',
                type: 'string',
                args: {
                    field: 'author_name',
                },
            },
            {
                label: 'Publication Year',
                type: 'string',
                args: {
                    field: 'publication_year',
                },
            },
            {
                label: 'Page Count',
                type: 'number',
                args: {
                    field: 'page_count',
                },
            },
        ];
    },
    getValues( { bindings } ) {
        // Implementation to retrieve values based on args.field
    },
} );

With this implementation, users will see “Author Name”, “Publication Year”, and “Page Count” as options in the Block Bindings UI dropdown when binding block attributes to your custom source.

Editor registration Core examples

There are a few examples in Core that can be used as reference.

• Post Meta. Source code
• Pattern overrides. Source code

Unregistering a source

Note: Since WordPress 6.7.

unregisterBlockBindingsSource unregisters a block bindings source by providing its name.

import { unregisterBlockBindingsSource } from '@wordpress/blocks';

unregisterBlockBindingsSource( 'plugin/my-custom-source' );

Getting all sources

Note: Since WordPress 6.7.

getBlockBindingsSources returns all registered block bindings sources.

import { getBlockBindingsSources } from '@wordpress/blocks';

const registeredSources = getBlockBindingsSources();

Getting one specific source

Note: Since WordPress 6.7.

getBlockBindingsSource return a specific block bindings source by its name.

import { getBlockBindingsSource } from '@wordpress/blocks';

const blockBindingsSource = getBlockBindingsSource( 'plugin/my-custom-source' );

Block Bindings Utils

Note: Since WordPress 6.7.

UseBlockBindingUtils is a hook with two helpers that allows developers to edit the metadata.bindings attribute easily.

It accepts a clientId string as a parameter, if it is not set, the function will use the current block client ID from the context.

Example:

import { useBlockBindingsUtils } from '@wordpress/block-editor';

const { updateBlockBindings } = useBlockBindingsUtils('my-block-client-id-12345');
...

updateBlockBindings

updateBlockBindings works similarly to updateBlockAttributes, and can be used to create, update, or remove specific connections.

import { useBlockBindingsUtils } from '@wordpress/block-editor';

const { updateBlockBindings } = useBlockBindingsUtils();

function updateBlockBindingsURLSource( url ) {
    updateBlockBindings( {
        url: {
            source: 'myplugin/new-source',
        },
    } );
}

// Remove binding from url attribute.
function removeBlockBindingsURLSource() {
    updateBlockBindings( { url: undefined } );
}

removeAllBlockBindings

removeAllBlockBindings will remove all existing connections in a block by removing the metadata.bindings attribute.

import { useBlockBindingsUtils } from '@wordpress/block-editor';

const { removeAllBlockBindings } = useBlockBindingsUtils();

function clearBlockBindings() {
    removeAllBlockBindings();
}