WordPress Block Bindings API: Guide For Developers (2026)

Until recently, connecting dynamic data like custom fields or post meta to Gutenberg blocks required workarounds: custom templates, block variations, or injecting server-rendered content. That complexity is now history.

Starting in WordPress 6.5 (March 2024), the Block Bindings API was introduced as an experimental feature. As of WordPress 6.8 (July 2025), it has significantly matured and is ready for real-world use in custom themes, plugins, and dynamic site builds.

The Block Bindings API allows developers to bind block attributes to external data sources—like post meta, without writing custom PHP or JavaScript render logic.

What is the Block Bindings API?

The Block Bindings API is a mechanism to dynamically populate a block’s attributes using declarative data sources.

With just a few lines of JSON, you can bind a block’s text, URL, image, or other attributes to:

Post meta fields (custom fields)
Site options (coming soon)
User profile data (coming soon)
Or even custom sources registered by plugins

This means you can build dynamic block-based layouts without touching a single template-parts/ PHP file.

Why the Block Bindings API Matters?

The Block Bindings API represents a major step forward in how we build dynamic, maintainable, and scalable WordPress sites — especially in the Gutenberg era. Here’s why this matters deeply to developers, product teams, and even clients:

1. No More Redundant Block Variations

Previously, if you wanted to output dynamic content like a custom field value inside a block, you had to either:

Create a custom block variation
Use InnerBlocks with locked templates
Fall back to render_callback PHP-based logic

With block bindings, you can bind any attribute to a dynamic data source directly in JSON, eliminating boilerplate and complexity. That means less code, fewer files, and faster development.

2. Decouples Logic from Presentation

WordPress has always mixed data logic and presentation — think the_title(), the_content(), etc. But in modern development, separation of concerns leads to cleaner architecture.

With bindings, the content source is defined declaratively in block.json, while the design stays inside the block template. This enables:

Theme switching without breaking layout logic
Clear, versionable templates
Easier onboarding for new developers

3. Works with Core and Custom Blocks

Whether you’re using core blocks like Paragraph, Heading, Image — or building your own — block bindings are flexible and composable.

You can now:

Reuse core blocks in custom ways without re-registering them
Make custom blocks smarter with less custom JS
Build theme patterns with dynamic behavior without a plugin dependency

It’s all native. No ACF hacks, no shortcode rendering, and no dependency on theme-specific functions.

4. Enables Better Editor Experience for Clients

With bindings, the content updates automatically inside the editor as it changes in the database — no need for clients to re-type, duplicate, or sync data manually.

Example:
A post’s location, author bio, or price can now be shown in a block that auto-updates, reducing client error and training overhead.

This leads to:

Cleaner content workflows
Fewer support tickets
Happier clients

5. Foundation for Future WordPress Features

Block Bindings are not just a convenience — they’re foundational to what’s coming in Phase 3 of the Gutenberg roadmap, including:

Collaborative editing (real-time content sync)
Field and form-based interfaces
Advanced pattern personalization (e.g., show different data per user)

Think of it as the React-style “props” system for blocks, enabling data-driven UI design that lives entirely in the editor.

6. Makes WordPress Feel Like a Framework

With block bindings, WordPress starts to feel less like a legacy CMS and more like a framework for modern web apps:

Declarative UI (like React or Vue)
Data-bound components (like Svelte or Angular)
Built-in design tokens (via theme.json)
Front-end rendering powered by native blocks and styles

It’s a signal that WordPress is ready to compete in the modern web dev world — without giving up its ease of use.

Example: Bind a Paragraph Block to Post Meta

Let’s walk through a practical, real-world example of how the Block Bindings API can replace what used to require PHP templates or custom blocks.

🎯 Scenario:

You’re building a “Meet the Speakers” page for an event website. Each speaker is a speaker custom post type with a custom field called job_title (e.g., “Data Scientist”, “CTO”, “Marketing Lead”).

You want to display this job title beneath each speaker’s name using a core Paragraph block — but you want it to pull from the post meta automatically.

Traditional Way (before bindings):

To achieve this previously, you might have:

Written a custom render_callback for a custom block.
Registered a block variation just to fetch and insert job_title.
Hard-coded the job title in PHP templates like single-speaker.php.
Used ACF blocks or shortcode workarounds.

Each of these approaches introduced technical debt, rigidity, or extra effort — not ideal.

Modern Way: With Block Bindings

Now, with the Block Bindings API, you can keep using the core Paragraph block and just tell it to pull data from the custom field.

Here’s the relevant JSON configuration in block.json:

{
  "attributes": {
    "content": {
      "type": "string",
      "source": "html",
      "selector": "p",
      "__experimentalRole": "content",
      "__experimentalBindTo": {
        "source": "core/post-meta",
        "args": {
          "key": "event_location"
        }
      }
    }
  }
}

What this does:

__experimentalRole: "content" tells WordPress that this attribute controls the block’s visible content.
__experimentalBindTo defines a data binding source.
source: "core/post-meta" targets post meta as the source of truth.
args.key is the name of the custom field — in this case, job_title.

The result?

The block will now automatically display the value of job_title from the current post — in both the editor and the frontend.
No custom PHP, no shortcode, no new block registration.
If the job title field is updated, the block reflects the new value instantly.

Supported Data Sources (as of WordPress 6.8)

As of WordPress 6.8, the Block Bindings API officially supports one core data source:

1. `core/post-meta` (Official)

This source allows block attributes to be bound to post meta fields — including any custom fields added through:

ACF (Advanced Custom Fields)
Custom code via register_post_meta()
Plugins like CPT UI
Manual insertion using update_post_meta()

This source is fully supported and documented in WordPress 6.8.

Official Docs:

Use Cases for Developers

The WordPress Block Bindings API empowers developers to build dynamic, flexible, and maintainable block-based websites by connecting block attributes directly to data sources. Here are some practical, real-world use cases that highlight how this API can transform your development workflow:

1. Streamlining Custom Field Integration Without PHP

Traditionally, displaying custom field data inside blocks meant writing custom PHP render callbacks or creating block variations. With the Block Bindings API, you can bind block attributes directly to post meta fields (including those managed by plugins like ACF) — all declaratively and without server-side code. For example, bind a core Paragraph block’s content to an ACF field subtitle to dynamically display post-specific subtitles inside the editor and front end. This reduces development complexity and keeps your block markup clean and reusable.

2. Creating Truly Dynamic Query Loop Templates

The Query Loop block is a powerful way to display lists of posts, but adding custom meta or dynamic data inside the loop usually requires additional PHP or custom blocks. Using block bindings, you can bind block attributes inside Query Loop items directly to post meta fields, enabling display of custom data like product prices, event dates, or author info. This allows fully dynamic loop templates with no need for custom server rendering and easier client management since content updates automatically when post meta changes.

3. Building Reusable Block Patterns with Dynamic Data

Developers can craft block patterns (pre-built block layouts) that include blocks bound to meta fields. This means patterns can be used across multiple posts or pages and always display up-to-date, relevant data. This greatly improves the flexibility of block patterns and makes them suitable for more complex use cases like landing pages, product showcases, or portfolio items.

4. Enabling Client-Friendly Content Editing

Since block bindings update dynamically in the editor, clients or content editors see real content rather than placeholders or hardcoded text. This enhances the editing experience and reduces confusion, training, and errors. Developers can deliver block-based sites where clients safely edit content and custom fields in a seamless, unified interface without jumping between editors or PHP templates.

5. Extending Blocks with Custom Dynamic Data via Plugin-Defined Sources

Beyond post meta, developers can register custom binding sources to fetch data from APIs, external services, or plugin-specific data stores. Examples include WooCommerce developers binding pricing, stock status, or custom product data to blocks dynamically; membership sites showing user-specific data such as subscription status or profile info inside blocks; or multisite/SaaS platforms pulling site-specific or tenant-specific data dynamically into block templates. This extensibility opens doors to building rich, app-like experiences inside WordPress using familiar block UI paradigms.

6. Accelerating Transition to Full Site Editing (FSE)

The Block Bindings API reduces the reliance on PHP templates for dynamic data and pairs perfectly with theme.json and other FSE features. Developers can build block-based themes and templates that are fully dynamic, easy to maintain, and client-editable, accelerating the adoption of FSE for complex sites.

How to Create Your Own Binding Source?

One of the most powerful capabilities of the WordPress Block Bindings API is the ability for plugin and theme developers to register custom binding sources. This lets you connect block attributes to any data your plugin or external service can provide, making your blocks truly dynamic and context-aware beyond the core post-meta data.

Why Create a Custom Binding Source?

By default, the API supports binding to post meta (core/post-meta), but you might want to:

Fetch data from an external API (e.g., weather, stock prices, analytics)
Pull plugin-specific data (e.g., WooCommerce product stock, user membership status)
Connect blocks to multisite-specific settings or user profile data
Provide dynamic, contextual content tailored to the current user or environment

Creating a custom source gives you the flexibility to integrate any data source into block attributes declaratively.

Step 1: Import the `registerBindingSource` Function

This API is provided as part of the @wordpress/block-bindings package.

import { registerBindingSource } from '@wordpress/block-bindings';

You typically include this in your plugin’s editor JavaScript entry point or wherever you initialize block registrations.

Step 2: Define and Register Your Binding Source

Call registerBindingSource() with a unique source name (namespaced to avoid conflicts) and an object that describes your data source.

registerBindingSource( 'myplugin/custom-data', {
  label: 'My Custom Data',
  getValue: ( context, args ) => {
    // Return the value to bind to the block attribute.
  },
});

label: A human-readable name for your source (useful in UI or debugging).
getValue: A function responsible for retrieving the data to bind.

Step 3: Implement the `getValue` Function

The heart of your custom source is the getValue function. It receives:

context: An object containing contextual information such as the current post, user, or site (depending on environment).
args: The arguments object passed via the block attribute’s __experimentalBindTo.args.

Your function must return a value synchronously or a Promise resolving to the value.

Example:

registerBindingSource( 'myplugin/custom-data', {
  label: 'My Custom Data',
  getValue: ( context, args ) => {
    // Example: Return a dynamic greeting with post title
    if ( context.post ) {
      return `Hello, this is data for post: ${ context.post.title }`;
    }
    return 'Default fallback data';
  },
});

You can also perform asynchronous operations, such as fetching from a REST API:

registerBindingSource( 'myplugin/async-api', {
  label: 'Async API Data',
  getValue: async ( context, args ) => {
    const response = await fetch(`https://api.example.com/data?id=${ args.id }`);
    const data = await response.json();
    return data.value;
  },
});

Step 4: Use Your Binding Source in Block Attributes

In your block’s block.json or programmatic registration, bind an attribute to your custom source:

{
  "attributes": {
    "content": {
      "type": "string",
      "source": "html",
      "selector": "p",
      "__experimentalRole": "content",
      "__experimentalBindTo": {
        "source": "myplugin/custom-data",
        "args": {
          "postId": 123
        }
      }
    }
  }
}

Here, args is passed to your getValue function as the second parameter, letting you customize data fetching per block instance.

Step 5: Handling Context Properly

The context argument provides useful information:

For blocks inside a post editor, it includes the post ID, type, and other details.
For front-end rendering, context may include site info, user data, or environment details.

Use context to dynamically determine what data to fetch or return.

Step 6: Testing and Debugging

Because block bindings can be asynchronous, test your bindings both in the editor and front end to ensure:

Correct and timely data retrieval
Proper fallback values when data is unavailable
No blocking UI or rendering issues

Use browser dev tools to debug getValue function behavior.

import { registerBindingSource } from '@wordpress/block-bindings';

registerBindingSource( 'myplugin/external-api', {
  label: 'External API',
  getValue: ( context, args ) => {
    return fetchMyValueFromAPI( context, args );
  }
});

Now you can use this in __experimentalBindTo just like the core ones.

Reference: Block Bindings API – Registering a Custom Source

Developer Tips

The Block Bindings API offers a powerful new way to connect block attributes to dynamic data sources, but leveraging it effectively requires understanding its nuances. Here are some essential tips to help you build robust, performant, and maintainable bindings:

1. Bind Only Supported Attributes

Focus on binding block attributes that directly affect output and are designed to accept dynamic content. Common attributes include content, url, value, alt, src, and other display-relevant fields. Binding unsupported or internal attributes may cause unexpected behavior or editor issues. Reference: The official Block Bindings API docs detail supported attributes for core blocks.

2. Use the `__experimentalRole` Property Correctly

The __experimentalRole helps the editor understand how bound attributes should behave. For example, "content" indicates the main display content. Assign roles carefully to ensure proper handling of editing, saving, and serialization.

3. Optimize `getValue` for Performance

If you’re registering a custom binding source, make sure your getValue function is performant and avoids blocking the editor UI. Use caching or memoization where possible to reduce redundant data fetching. Asynchronous operations should resolve quickly or fallback gracefully.

4. Provide Fallbacks and Handle Missing Data

Blocks bound to data sources may sometimes receive empty or undefined values. Design your blocks to handle these cases gracefully, show meaningful fallback text or placeholders to maintain a good editing experience and prevent front-end rendering issues.

5. Understand Context Availability

The context parameter passed to getValue contains useful environmental data like the current post, user, or site. Use this to tailor data fetching logic. However, context availability may vary between editor and front-end render, so test thoroughly in both environments.

6. Avoid Binding to Highly Dynamic or Frequently Changing Data

Binding attributes to rapidly changing data (e.g., real-time analytics, stock tickers) can cause performance or synchronization issues. For such cases, consider alternative approaches like client-side React state or server-rendered dynamic blocks.

7. Namespace Custom Binding Sources

Use a clear and unique namespace when registering custom sources to prevent conflicts with other plugins or core. For example, use your plugin slug: 'myplugin/custom-source'.

8. Test Across Editor and Frontend

Bindings should work seamlessly both in the block editor and on the site’s frontend. Test your blocks in different contexts to confirm that bound data renders correctly and updates as expected.

9. Keep Accessibility in Mind

When displaying dynamic content via bindings, ensure that accessibility is preserved. For example, provide meaningful alt text for images bound to meta, and verify screen reader compatibility.

10. Monitor WordPress Core Updates

The Block Bindings API is evolving. Keep an eye on official WordPress release notes and documentation to stay updated on API changes, new data sources, and improved support.

Final Thoughts

The WordPress Block Bindings API marks a significant milestone in the evolution of block-based development. By enabling developers to declaratively connect block attributes directly to dynamic data sources, starting with core/post-meta and extensible via custom sources, it dramatically simplifies how dynamic content is integrated into Gutenberg blocks.

This approach reduces reliance on PHP templates and complex server-side rendering, promoting a clean separation between data and presentation. It accelerates development by cutting down boilerplate and making blocks more reusable and client-friendly. Whether you’re building custom field integrations, dynamic Query Loop templates, or plugin-powered personalized content, the Block Bindings API provides a modern, scalable foundation.

By registering your own binding sources, you can extend the power of this API to integrate virtually any data — external APIs, plugin data stores, user profiles — right into block attributes, opening doors for rich, app-like WordPress experiences.

Following best practices such as binding only supported attributes, optimizing data retrieval for performance, handling fallback cases, and thorough testing ensures that your dynamic blocks provide a seamless experience both in the editor and on the front end.

As the API matures and adoption grows, it will become a cornerstone for Full Site Editing themes, reusable dynamic patterns, and complex site architectures, helping WordPress move closer to a true modern content framework.

For developers ready to build the next generation of WordPress sites and plugins, mastering the Block Bindings API is an essential step toward cleaner, faster, and more maintainable block-based development.