Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared Managed Cloud India
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Best lists Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Developer · Guide

How to Use Block Bindings in WordPress

Short answer

To use block bindings in WordPress, register a custom field with show_in_rest set to true, add a value to that field, then connect a supported block attribute to it with the core/post-meta source. WordPress 6.5 or later is required, and on WordPress 6.9 or later you can pick the field in the editor Attributes panel.

Key takeaways

  • Block bindings need WordPress 6.5 or later and connect a block attribute to a data source such as post meta.
  • A custom field must be registered with show_in_rest set to true, and its key must not start with an underscore.
  • Only 7 core blocks support bindings by default, including Paragraph, Heading, Image and Button.
  • On WordPress 6.5 to 6.8 you add a binding in the Code Editor, while WordPress 6.9 or later adds an Attributes panel picker.
  • A bound block shows the field value on the front end, and editing the field updates every block bound to it.
  • WordPress 6.6 or later lets you edit a bound custom field value directly from the connected block.

What do you need before you use block bindings?

You need WordPress 6.5 or later, a field that holds the value, and a supported block to show it.

Block bindings connect a block attribute to a data source, and WordPress then shows the source value on the front end. The Block Editor Handbook states that the Block Bindings API is only available for WordPress 6.5 and above.

WordPress 6.5, named Regina, was released on April 2, 2024. The WordPress 6.5 release page says it lets you link core block attributes to custom fields without creating custom blocks.

Check your version first at Dashboard, then Updates. If you run an older version, update WordPress before you start.

You also need somewhere to put the code that registers your field. Use a child theme or a small custom plugin for that code, and keep a backup before you edit theme files. Our guide to how to back up WordPress walks through the backup step.

Plan about 30 minutes for your first binding, including the code and a front-end check. Later bindings take a few minutes each once the field exists.

How do you register a custom field for block bindings?

Register the field in PHP with show_in_rest set to true so the editor and the bindings system can read it.

A custom field is a named value stored with a post, such as a subtitle or a price. The field must exist in code before a binding can use it, because typing a name into the Custom Fields panel alone does not register it.

The Block Editor Handbook gives this exact pattern for a post field:

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

Add that code to your child theme functions.php file or to a small plugin, and change my_custom_field to your own key. Use lowercase letters and underscores, and do not start the key with an underscore.

The handbook lists 2 rules for the core/post-meta source: the field must be registered with show_in_rest set to true, and the key cannot start with an underscore. Protected keys that start with an underscore are not accessible to bindings.

If the field belongs to a page rather than a post, change the first argument from post to page. The difference between the two content types matters here, so see posts vs pages in WordPress if you are unsure which one you are editing.

What if you use a custom field plugin?

Some field plugins register fields for the REST API for you, so check the plugin docs before you write code.

ACF 6.8.1 or later adds full support for block bindings, and it needs WordPress 6.7 or later. The ACF block bindings docs say you must turn on “Allow Access to Value in Editor UI” for each field you want to bind.

How do you add a value to the custom field?

Add the value in the Custom Fields panel below the post editor, using the exact key you registered.

First, show that panel. Open the post, click the Options menu (the 3 dots at the top right), then Preferences, then turn on the Custom fields toggle. The editor reloads after you turn it on, so save your draft first.

Scroll to the Custom Fields panel at the bottom of the post. Click “Enter new”, type your key in the Name column, type the value in the Value column, then click “Add Custom Field”.

Use a short plain value for your first binding, such as a subtitle of 5 to 10 words. Long HTML or a list does not fit a single block attribute, so keep the value to one line of text, one number, or one URL.

Repeat this step on each post that needs its own value. A binding reads the field from the current post, so each post can show a different subtitle, price, or link.

How do you bind a block in the editor?

Select a supported block, open its Attributes panel, pick the attribute, then pick your field as the source.

This picker is the no-code path, and it needs WordPress 6.9 or later. The Meta Box block bindings docs state that the Attributes panel is available from WordPress 6.9 onward, and that on WordPress 6.5 to 6.8 you bind attributes in the Code Editor instead.

Follow these steps on WordPress 6.9 or later:

  1. Open the post or template in the editor.
  2. Add a Paragraph, Heading, Image or Button block.
  3. Select the block and open the Block settings sidebar.
  4. Open the “Attributes” panel near the bottom.
  5. Click the attribute you want to bind, such as “Content”.
  6. Pick “Post Meta” as the source, then pick your field.

The block shows a visual marker when it is bound, and its text becomes the field value. Save the post when the binding looks right.

If you use ACF, the steps match, except you pick “ACF Field” as the source instead of “Post Meta”. Only fields with “Allow Access to Value in Editor UI” turned on appear in that list.

How do you bind a block with code in a template?

Add a metadata.bindings object to the block markup, naming the source and the field key.

This is the path for WordPress 6.5 to 6.8, and it is also how you bind blocks inside a block theme template. Open the template in the Site Editor at Appearance, then Editor, then Templates, and pick the template you want to change.

Switch to the Code Editor from the Options menu, find the block, and add the binding object. The Block Editor Handbook shows this Paragraph example:

"metadata": {
  "bindings": {
    "content": {
      "source": "core/post-meta",
      "args": { "key": "my_custom_field" }
    }
  }
}

The fallback text inside the block shows in the editor, and WordPress replaces it with the field value on the front end.

Switch back to the Visual Editor and save the template. Check the front end on a post that has a value in the field, and on one that does not, so you can see what visitors see in each case.

Which blocks and attributes can you bind?

You can bind 7 core blocks by default, and each block only exposes the attributes in the list below.

Not every block works with bindings yet. The handbook lists the default set, and a block outside this set ignores a binding until a developer extends support for it.

BlockAttributes you can bind
Imageid, url, title, alt, caption
Headingcontent
Paragraphcontent
Buttonurl, text, linkTarget, rel
Navigation Linkurl
Navigation Submenuurl
Post Datedatetime

That is 7 blocks and 15 attributes in total across the table. A Paragraph or Heading only binds its content, while an Image binds 5 attributes, including its URL and alt text.

If you need another block or attribute, a developer can extend the list with a filter. The handbook notes that the block_bindings_supported_attributes filter arrived with WordPress 6.9, and it also affects which attributes pattern overrides can use.

Choosing a block from this list first saves time. A block editor vs page builder comparison can help if you are still deciding how much of your layout should live in core blocks at all.

What else can you bind to besides a custom field?

WordPress ships 4 built-in sources, and each one reads a different kind of data.

Post meta is the source you will use most, because it reads a custom field from the current post. The other 3 sources cover post data, term data, and pattern overrides.

SourceWhat it readsExample use
core/post-metaA custom field on the current postShow a subtitle stored in a field
core/post-dataPost date, modified date, or linkShow the last modified date
core/term-dataTerm name, link, slug, or countList category names in a query
core/pattern-overridesA per-instance override valueLet each pattern copy change one line

The core/post-data source offers 3 fields: date, modified, and link. The handbook marks this source as available since WordPress 6.9.

The core/term-data source offers 7 fields: id, name, link, slug, description, parent, and count.

It needs termId and taxonomy from block context, so use it inside a term template or a terms query. Terms are the values behind categories and tags, as explained in categories vs tags in WordPress.

The core/pattern-overrides source lets each copy of a synced pattern change specific blocks while the rest stays in sync. You mark a block as overridable in the pattern with metadata.bindings and a metadata.name key, and each instance stores its own override value.

How do you register a custom binding source?

Register a custom source in PHP when the value does not live in post meta, post data, or term data.

A custom source is a named function that returns a value for a block attribute. Use one for computed values, such as a reading time, or for data from another place, such as a site option or an outside API.

Call register_block_bindings_source() from a function attached to the init hook. The handbook says registration needs at least a name, a label, and a get_value_callback function.

add_action(
    'init',
    function () {
        register_block_bindings_source(
            'my-plugin/reading-time',
            array(
                'label'              => __( 'Reading Time', 'my-plugin' ),
                'get_value_callback' => 'my_plugin_get_reading_time',
                'uses_context'       => array( 'postId' ),
            )
        );
    }
);

The callback receives 3 arguments: source_args, block_instance, and attribute_name. It must return the value for the attribute, and WordPress can pass that value through the block_bindings_source_value filter before it renders.

Once the source is registered, any supported block can read from it through metadata.bindings. Use the same source name in PHP and in the block markup, or the binding will not resolve.

A custom source is developer work, so keep it in a plugin rather than a theme file if the data should survive a theme change. The theme vs plugin guide explains where this kind of feature belongs.

How do you check that a binding worked?

View the post on the front end while logged out, and confirm the block shows the field value.

The editor shows fallback text, so the editor alone does not prove the binding works. Open the live post in a private browser window and compare the block text with the value in the Custom Fields panel.

Run these 4 checks:

  1. The bound block shows the field value on the front end.
  2. Changing the field value and reloading the post changes the block.
  3. A post with no value in the field shows the fallback or an empty block, as you planned.
  4. Other blocks on the page still show their own text.

If the value does not appear, check the key spelling first, then check that show_in_rest is true. A single wrong letter in the key breaks the link, and the block falls back to its saved text.

WordPress 6.6 or later also lets you edit a bound custom field value directly from the connected block. Make WordPress Core explains that this editing was added in WordPress 6.6, after bound blocks were locked in WordPress 6.5.

What mistakes should you avoid?

Do not bind a field you never registered, do not use a protected key, and do not expect every block to work.

The most common mistake is adding a name and value in the Custom Fields panel without registering the field in code. The binding then has nothing to read, and the block keeps its fallback text.

Avoid these 5 mistakes:

  • Using a key that starts with an underscore, which bindings cannot read.
  • Binding a Gallery, List, or other block outside the supported list of 7.
  • Putting HTML, a list, or several lines into a field that feeds one text attribute.
  • Editing the bound text in the editor and expecting the field to change on older versions.
  • Renaming a field key after posts already use it, which breaks every binding that names the old key.

Test on a staging copy or a draft post before you bind blocks in a live template. A wrong binding in a template affects every post that uses that template, so one test post is not enough.

If a binding stops working after a change, remove the binding from the block and add it again with the current key. That step clears a stale connection faster than hunting through the template code.

Frequently asked questions

Do block bindings need a plugin?

No. The core/post-meta source works with no plugin once you register the field in code with show_in_rest set to true. A field plugin such as ACF or Meta Box can register fields and add a picker, but it is optional. WordPress 6.5 or later already ships the Block Bindings API in core.

Why does my bound block still show the old text?

The block is probably showing its fallback text because the binding cannot read the field. Check that the key matches exactly, that the field is registered with show_in_rest set to true, and that the current post actually has a value in that field. Also confirm the block is one of the 7 supported core blocks.

Can I edit a bound block by typing in it?

In WordPress 6.5 the bound block was locked, so you could not type in it. WordPress 6.6 or later lets you edit the bound custom field value directly from the connected block. The change updates the field itself, so every other block bound to the same field shows the new value too.

Can block bindings show a list or a repeater field?

No, not directly. A binding maps one block attribute to one single value, such as a string, a number, or a URL. A repeater or group field holds several values at once, so it does not fit one attribute. Use a custom source or a different block for grouped data instead.

Do bindings work in classic themes?

Yes, the API works in classic themes too, because bindings are resolved when WordPress renders the block. The no-code picker and the template steps in this guide assume the block editor and the Site Editor, which are easiest in a block theme. In a classic theme you add the binding markup to the block content instead.

What happens if I delete the custom field?

The binding stays in the block markup, but it has no value to read. The block then shows its fallback text on the front end, or nothing if there is no fallback. Remove the binding or point it at a field that still exists, and check every template that used the deleted field.

Sources

  1. Bindings – Block Editor Handbook WordPress Developer Resources
  2. Introducing Block Bindings, part 1: connecting custom fields WordPress Developer Blog
  3. WordPress 6.5 Regina WordPress.org
  4. Editing custom fields from connected blocks Make WordPress Core
  5. Block Bindings Advanced Custom Fields
  6. Block bindings Meta Box Documentation

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

WPLegible editors

Researched from the primary sources listed above and checked against our editorial rules. About the site · How we test