Title: block-api – Make WordPress Core --- # Tag Archives: block-api [ ](https://profiles.wordpress.org/dmsnell/) [Dennis Snell](https://profiles.wordpress.org/dmsnell/) 6:11 pm _on_ November 19, 2025 Tags: [6-9 ( 87 )](https://make.wordpress.org/core/tag/6-9/), block-api, [dev-notes ( 617 )](https://make.wordpress.org/core/tag/dev-notes/), [dev-notes-6-9 ( 25 )](https://make.wordpress.org/core/tag/dev-notes-6-9/)    # 󠀁[Introducing the streaming block parser in WordPress 6.9](https://make.wordpress.org/core/2025/11/19/introducing-the-streaming-block-parser-in-wordpress-6-9/)󠁿 WordPress 6.9 introduces the `WP_Block_Processor` class — a new tool inspired by the HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. and designed for efficiently scanning, understanding, and modifying blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. structure in HTML documents. Continue on to learn about this new class, its use-cases, and how you can take advantage of it for more efficient server-side processing. [Continue reading →](https://make.wordpress.org/core/2025/11/19/introducing-the-streaming-block-parser-in-wordpress-6-9/#more-119384) [#6-9](https://make.wordpress.org/core/tag/6-9/), [#block-api](https://make.wordpress.org/core/tag/block-api/), [#dev-notes](https://make.wordpress.org/core/tag/dev-notes/), [#dev-notes-6-9](https://make.wordpress.org/core/tag/dev-notes-6-9/) [ ](https://profiles.wordpress.org/thekt12/) [Karthik Thayyil](https://profiles.wordpress.org/thekt12/) 3:15 pm _on_ February 29, 2024 Tags: [6-5 ( 76 )](https://make.wordpress.org/core/tag/6-5/), block-api, [dev-notes ( 617 )](https://make.wordpress.org/core/tag/dev-notes/), [dev-notes-6.5 ( 15 )](https://make.wordpress.org/core/tag/dev-notes-6-5/)    # 󠀁[Performance improvements for registering block variations with callbacks](https://make.wordpress.org/core/2024/02/29/performance-improvements-for-registering-block-variations-with-callbacks/)󠁿 ## Background In **WordPress 5.8**, the APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. for registering blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. variations was introduced, bringing new capabilitiescapability A **capability** is permission to perform one or more types of task. Checking if a user has a capability is performed by the `current_user_can` function. Each user of a WordPress site might have some permissions but not others, depending on their role. For example, users who have the Author role usually have permission to edit their own posts (the “edit_posts” capability), but not permission to edit other users’ posts (the “edit_others_posts” capability). to developers. However, it soon became evident that generating these variations had a non-trivial performance cost, particularly when used for `template-part` and `navigation-link` in **WordPress 5.9** and `post-terms` in **WordPress 6.1**. The coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. of this issue was that these variations were being generated on every page load due to their registration using the `init` hook. This was inefficient, as the variations were only needed in the editor or for returning block data in the REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) [https://developer.wordpress.org/rest-api/](https://developer.wordpress.org/rest-api/). This redundancy in loading led to unnecessary performance overhead, underscoring the need for a more streamlined approach. ## What is changed In WordPress 6.5, we’ve introduced `$variation_callback` as a new attribute in WP_Block_Type. This feature allows developers to register variation-building functions as callbacks rather than building variations before registration. With this approach, variations are constructed from this callback only when they are accessed for the first time. Consequently, the `WP_Block_Type::get_variations()` method was introduced as the primary means to access variations. This method skillfully checks for a callback in `variation_callback` and triggers the callback, but only during the first access of the variations. This efficient approach ensures that the callback is executed just once, optimizing performance by avoiding redundant processing on subsequent accesses. Additionally, this strategy aids in lazy loading, as variations no longer need to be loaded during registration. Moreover, it integrates the `get_block_type_variations` filterFilter Filters are one of the two types of Hooks [https://codex.wordpress.org/Plugin_API/Hooks](https://codex.wordpress.org/Plugin_API/Hooks). They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output., which provides a versatile mechanism for developers to modify the resulting variations. These enhancements reflect WordPress’s ongoing commitment to improving its developer-centric features and maintaining compatibility with existing functionalities. In WordPress 6.5, a significant alteration is made to `WP_Block_Type::$variations`. The notable change involved transitioning the visibility of variations from public to private. This modification was specifically designed to necessitate the use of the PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher magic `__get` method for accessing variations only via `WP_Block_Type::get_variations()`. Please note that the modifications to `WP_Block_Type::$variations` may introduce certain limitations that require developer attention. These are detailed in the “ Developer Action” section below. ## Lazy loading variations using `variation_callback` To facilitate the lazy loading of variations, we can replace the traditional method of loading variations with a callback. This approach is exemplified in the case of GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/) [PR #56952](https://github.com/WordPress/gutenberg/pull/56952), which is aimed at enhancing performance. Previously, `template-part` variations were loaded as follows: ```php register_block_type_from_metadata(    __DIR__ . '/template-part',    array(        'render_callback'    => 'render_block_core_template_part',        'variations'         => build_template_part_block_variations(),    )); ``` To optimize this, we have transitioned to using a `variation_callback`: ```php register_block_type_from_metadata(    __DIR__ . '/template-part',    array(        'render_callback'    => 'render_block_core_template_part',        'variation_callback' => 'build_template_part_block_variations',    )); ``` It’s important to note that if both `variations` and `variation_callback` are defined, like in the following example: ```php register_block_type_from_metadata( 'block-name', array( 'variations' => array( 'test-variation' => array( 'test-variations' ) ), 'variation_callback' => 'get_test_variations', )); ``` In this scenario, the variations array takes precedence, and the `variation_callback` will not be called. ## Developer action required With the addition of `variations` to the existing magic function framework in `WP_Block_Type`, a significant limitation emerges: the inability to modify variations by reference directly. This change impacts how variations were traditionally updated. Consider these examples of updating variations by reference, which will no longer function as expected in WordPress 6.5: ```php $block_type->variations[] = array( 'test' => array( 'test' ) );// or$block_type->variations['example1'] = array( 'test' ); ``` To overcome this limitation in WordPress 6.5, a workaround involving a temporary variable can be used. Here’s how you can modify the temporary variable and then reassign it back to `$block_type->variations`: ```php $variations = $block_type->variations; $variations[] = array( 'test' => array( 'test' ) ); $block_type->variations = $variations; // Similarly $variations = $block_type->variations; $variations['example1'] = array( 'test' );$block_type->variations = $variations; ``` Alternatively, to align with the latest updates and best practices in WordPress, you might consider using the `get_block_type_variations` filter ([reference link](https://github.com/WordPress/wordpress-develop/blob/2ae28c50f9e97fcf96205ddd8597ceb8892f70ed/src/wp-includes/class-wp-block-type.php#L609)). ## Utilizing the `get_block_type_variations` filter for enhanced variation management The introduction of the `get_block_type_variations` filter in WordPress 6.5 allows for the manipulation and customization of the variations array, providing greater flexibility in handling block variations. Here’s an implementation example of the `get_block_type_variations` filter: ```php function modify_block_type_variations( $variations, $block_type ) { // Example: Add a new variation if ( 'block-name' === $block_type->name ) { $variations[] = array( 'name' => 'new-variation', 'title' => __( 'New Variation', 'textdomain' ), // Other variation properties... ); } return $variations;}add_filter( 'get_block_type_variations', 'modify_block_type_variations', 10, 2 ); ``` In this example, the `modify_block_type_variations` function is hooked to the `get_block_type_variations` filter. It checks if the block type is ‘`block-name`‘ and then adds a new variation to the variations array. This function then returns the modified variations array. By leveraging this filter, developers can dynamically adjust the variations according to specific requirements or conditions. Please refer to [#59969](https://core.trac.wordpress.org/ticket/59969) for additional details on these changes. Props to [@adamsilverstein](https://profiles.wordpress.org/adamsilverstein/), [@westonruter](https://profiles.wordpress.org/westonruter/), [@joemcgill](https://profiles.wordpress.org/joemcgill/), and [@leonnugraha](https://profiles.wordpress.org/leonnugraha/) for reviewing this post. [#6-5](https://make.wordpress.org/core/tag/6-5/), [#block-api](https://make.wordpress.org/core/tag/block-api/), [#dev-notes](https://make.wordpress.org/core/tag/dev-notes/), [#dev-notes-6-5](https://make.wordpress.org/core/tag/dev-notes-6-5/) [ ](https://profiles.wordpress.org/ndiego/) [Nick Diego](https://profiles.wordpress.org/ndiego/) 5:05 pm _on_ August 17, 2023 Tags: block-api, [blocks ( 5 )](https://make.wordpress.org/core/tag/blocks/), [hallwayhangout ( 15 )](https://make.wordpress.org/core/tag/hallwayhangout/)    # 󠀁[Hallway Hangout: Let’s explore the power of block variations](https://make.wordpress.org/core/2023/08/17/hallway-hangout-lets-explore-the-power-of-block-variations/)󠁿 Join Ryan Welcher ([@welcher](https://profiles.wordpress.org/welcher/)) and me next month for a casual conversation about blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. variations and how you can use them to enhance the editing experience in WordPress. An often overlooked feature, variations are a great way to extend existing blocks and can be as simple or complex as you like. Many WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. blocks you use daily are variations! To kick off the discussion, we will provide a brief overview of what variations are and how they work. Ryan will then share how he built the [Advanced Query Loop](https://wordpress.org/plugins/advanced-query-loop/) pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress. org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) or can be cost-based plugin from a third-party. and why he opted for a variation of the Query block instead of building a custom block from scratch. And if you have built any variations or are using them in interesting ways, we encourage you to share them with the group.  While block variations tend to be a more developer-focused topic, this Hallway Hangout will be accessible to everyone. The event will be held on **Thursday, September 14, 2023, at 1:00 PM CST (18:00 UTC)**. The meeting link will be shared through the Learn WordPress MeetupMeetup All local/regional gatherings that are officially a part of the WordPress world but are not WordCamps are organized through [https://www.meetup.com/](https://www.meetup.com/). A meetup is typically a chance for local WordPress users to get together and share new ideas and seek help from one another. Searching for ‘WordPress’ on meetup.com will help you find options in your area. group. [RSVP for the event](https://www.meetup.com/learn-wordpress-online-workshops/events/295508765/) to access the link.  ## Recording ## Notes The Hallway Hangout was attended by **34 community members**, including facilitators @ndiego and [@welcher](https://profiles.wordpress.org/welcher/).  Nick gave a brief overview of what Block Variations are and how to use them. Ryan then discussed how and why you might want to build more advanced variations and demoed his Advanced Query LoopLoop The Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. [https://codex.wordpress.org/The_Loop](https://codex.wordpress.org/The_Loop) plugin. Questions were asked and answered throughout. The following resources were shared during the event: * [An introduction to block variations](https://developer.wordpress.org/news/2023/08/an-introduction-to-block-variations/)( WordPress Developer Blogblog (versus network, site) post) * The [developer documentation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-variations/) for Block Variations. * The [code reference](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/) for all Core blocks and their attributes. * The GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged by the repository owner. [https://github.com/](https://github.com/) [repository](https://github.com/ryanwelcher/advanced-query-loop) for the Advanced Query Loop plugin. * Ways to modify frontend markup of a block using `[render_block](https://developer.wordpress.org/reference/functions/render_block/)` and [block filters](https://developer.wordpress.org/block-editor/reference-guides/filters/block-filters/). * The next event: [Hallway Hangout: What’s new for developers in WordPress 6.4](https://www.meetup.com/learn-wordpress-online-workshops/events/296105065/)( October 12th)[](https://www.meetup.com/learn-wordpress-online-workshops/events/296105065/attendees/) _Props to [@welcher](https://profiles.wordpress.org/welcher/) for review._ [#block-api](https://make.wordpress.org/core/tag/block-api/), [#blocks](https://make.wordpress.org/core/tag/blocks/), [#hallwayhangout](https://make.wordpress.org/core/tag/hallwayhangout/) [ ](https://profiles.wordpress.org/juanmaguitar/) [JuanMa Garrido](https://profiles.wordpress.org/juanmaguitar/) 3:53 pm _on_ August 15, 2023 Tags: block-api, [block-developer-experience ( 5 )](https://make.wordpress.org/core/tag/block-developer-experience/), [gutenberg ( 538 )](https://make.wordpress.org/core/tag/gutenberg/), [interactivity API ( 11 )](https://make.wordpress.org/core/tag/interactivity-api/) # 󠀁[Status update on the Interactivity API](https://make.wordpress.org/core/2023/08/15/status-update-on-the-interactivity-api/)󠁿 The[ Interactivity API proposal](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/) was published a few months ago. This APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. aims to create a new standard for WordPress that simplifies and empowers building rich interactive web applications with WordPress using [declarative and reactive](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/#declarative-and-reactive) programming principles.  Since the proposal was published, a dedicated group of contributors has been focused on incorporating the Interactivity API into the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/) project, albeit in an experimental capacity. Fresh documentation resources have also been prepared to guide you through this API’s exciting possibilities. While the Interactivity API is experimental, you can already start exploring its potential, testing its features, and exploring what’s to come. This update shares the current state of the Interactivity API, the avenues to track its progress, the learning resources available, and how you can contribute. ## **Table of Contents** * [**Current Status and RoadMap**](https://make.wordpress.org/core/2023/08/15/status-update-on-the-interactivity-api/#current-status-and-roadmap) - [What’s its current status?](https://make.wordpress.org/core/2023/08/15/status-update-on-the-interactivity-api/#what-s-its-current-status) - [What lies ahead in the roadmap?](https://make.wordpress.org/core/2023/08/15/status-update-on-the-interactivity-api/#what-lies-ahead-in-the-roadmap) - [Keeping Tabs on Progress](https://make.wordpress.org/core/2023/08/15/status-update-on-the-interactivity-api/#keeping-tabs-on-progress) * [**Learning Resources**](https://make.wordpress.org/core/2023/08/15/status-update-on-the-interactivity-api/#learning-resources) - [Where can I find technical documentation?](https://make.wordpress.org/core/2023/08/15/status-update-on-the-interactivity-api/#where-can-i-find-technical-documentation) - [How can I get started?](https://make.wordpress.org/core/2023/08/15/status-update-on-the-interactivity-api/#how-can-i-get-started) - [Where can I ask questions?](https://make.wordpress.org/core/2023/08/15/status-update-on-the-interactivity-api/#where-can-i-ask-questions) * [**Contribute to the project**](https://make.wordpress.org/core/2023/08/15/status-update-on-the-interactivity-api/#contribute-to-the-project) - [How can I contribute?](https://make.wordpress.org/core/2023/08/15/status-update-on-the-interactivity-api/#how-can-i-contribute) - [Where can I share my feedback?](https://make.wordpress.org/core/2023/08/15/status-update-on-the-interactivity-api/#where-can-i-share-my-feedback) * [**Summary**](https://make.wordpress.org/core/2023/08/15/status-update-on-the-interactivity-api/#summary) ## **Current Status and RoadMap** _Wondering about the current state of affairs and how to stay in the loopLoop The Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. [https://codex.wordpress.org/The\_Loop](https://codex.wordpress.org/The_Loop)? Let’s dive right in._ ### **What’s its current status?** The [Interactivity API was added to Gutenberg 16.2](https://make.wordpress.org/core/2023/07/14/whats-new-in-gutenberg-16-2-12-july/#interactivity-api) as the [`interactivity` package](https://github.com/WordPress/gutenberg/tree/trunk/packages/interactivity). It’s worth noting that this package is only accessible within Gutenberg, as it is still very experimental and prone to changes. Some coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. blocks are [already embracing the Interactivity API’s](https://github.com/search?q=repo%3AWordPress%2Fgutenberg%20%40wordpress%2Finteractivity&type=code) potential, but its integration is still very limited. Contributors are still working on the [experimental Interactivity API](https://github.com/WordPress/gutenberg/tree/trunk/packages/interactivity) in Gutenberg. This work is being tracked at [Tracking Issue: Expose the full Interactivity API in @wordpress/interactivity](https://github.com/WordPress/gutenberg/issues/51056). ### **What lies ahead in the roadmap?** The list of tasks planned for the Interactivity API is available in the [Roadmap – Current list of tasks](https://github.com/WordPress/gutenberg/discussions/52904) discussion. This roadmap evolves and adapts as contributors learn more about the needs of this initiative. ### **Keeping Tabs on Progress** The ongoing work on the Interactivity API is held at the [Gutenberg repository](https://github.com/WordPress/gutenberg): * Collaborations and conversations happen in the [Interactivity API discussions](https://github.com/WordPress/gutenberg/discussions/categories/interactivity-api). * The Interactivity API is being developed under the distinctive label [[Feature] Interactivity API](https://github.com/WordPress/gutenberg/issues?q=label%3A%22%5BFeature%5D+Interactivity+API%22). A good way to keep track of the development of the Interactivity API is to subscribe to [Roadmap – Current list of tasks](https://github.com/WordPress/gutenberg/discussions/52904), as this discussion will be updated whenever new Tracking Issues are introduced or fresh plans emerge for this proposal’s future. Given its experimental state, rapid iterations and occasional disruptions are expected. The [Changelog – Tracking Breaking Changes in the Interactivity API](https://github.com/WordPress/gutenberg/discussions/52906) discussion ensures you’re properly informed about any breaking change on new Gutenberg releases. ## Learning Resources _Ready to expand your knowledge about the Interactivity API? Here’s where to start._ ### **Where can I find technical documentation?** Technical documentation for the Interactivity API can be located within the [`docs` folder of the `interactivity` package](https://github.com/WordPress/gutenberg/tree/trunk/packages/interactivity/docs). This documentation currently hosts the following resources: * [“Getting Started” guide](https://github.com/WordPress/gutenberg/blob/trunk/packages/interactivity/docs/1-getting-started.md) * [API Reference](https://github.com/WordPress/gutenberg/blob/trunk/packages/interactivity/docs/2-api-reference.md) Bear in mind that this documentation is still a work in progress, so don’t hesitate to [open a new discussion](https://github.com/WordPress/gutenberg/discussions/new?category=interactivity-api) to ask any questions. If you want to contribute to documentation efforts, join the [Coordinating our documentation efforts](https://github.com/WordPress/gutenberg/discussions/51928) discussion. The [Getting Started – and other learning resources](https://github.com/WordPress/gutenberg/discussions/52894) discussion is your go-to source for updates on new learning materials about the Interactivity API. ### **How can I get started?** To get started with the Interactivity API, you can follow this [Quick Start Guide](https://github.com/WordPress/gutenberg/blob/trunk/packages/interactivity/docs/1-getting-started.md#quick-start-guide) taking into account the [current requirements of the Interactivity API](https://github.com/WordPress/gutenberg/blob/trunk/packages/interactivity/docs/1-getting-started.md#requirements-of-the-interactivity-api). This guide will show you how to create your first interactive blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. with the Interactivity API that you can test in your WordPress projects. Once your interactive block is up and running, you can learn more from the [Interactivity API Reference](https://github.com/WordPress/gutenberg/blob/trunk/packages/interactivity/docs/2-api-reference.md) to continue adding interactivity to your blocks with this API. ### **Where can I ask questions?** The [Interactivity API Discussions](https://github.com/WordPress/gutenberg/discussions/52882) is the best place to ask questions about the Interactivity API.  ## Contribute to the project. _Eager to contribute to the Interactivity API’s evolution? Your input is invaluable._ ### **How can I contribute?** The best way to contribute to the Interactivity API is to share your ideas or suggestions in the [Interactivity API discussions.](https://github.com/WordPress/gutenberg/discussions/categories/interactivity-api) If you’re interested in helping with [specific issues related to the Interactivity API](https://github.com/WordPress/gutenberg/issues?q=label%3A%22%5BFeature%5D+Interactivity+API%22) feel free to comment on them to offer your help or add your insights. ### **Where can I share my feedback?** The [Interactivity API Discussions](https://github.com/WordPress/gutenberg/discussions/52882) is the best place to share your feedback about the Interactivity API.  ## Summary * The [Interactivity API is available in Gutenberg from version 16.2](https://make.wordpress.org/core/2023/07/14/whats-new-in-gutenberg-16-2-12-july/#interactivity-api), encapsulated within the [“interactivity” package](https://github.com/WordPress/gutenberg/tree/trunk/packages/interactivity). - Technical documentation is nestled within the [“docs” folder of this package](https://github.com/WordPress/gutenberg/tree/trunk/packages/interactivity/docs). * The ongoing work on the Interactivity API is being held at the [Gutenberg repository](https://github.com/WordPress/gutenberg): - Conversations and collaborations are taking place in [Interactivity API discussions](https://github.com/WordPress/gutenberg/discussions/categories/interactivity-api). - The Interactivity API is developed under the label[ [Feature] Interactivity API](https://github.com/WordPress/gutenberg/issues?q=label%3A%22%5BFeature%5D+Interactivity+API%22). * The following discussions are excellent references to keep track of this proposal: - [Getting Started – and other learning resources](https://github.com/WordPress/gutenberg/discussions/52894) - [Roadmap – Current list of tasks](https://github.com/WordPress/gutenberg/discussions/52904) - [Changelog – Tracking Breaking Changes in the Interactivity API](https://github.com/WordPress/gutenberg/discussions/52906) As WordPress advances toward more powerful interactive experiences, seize the opportunity to engage. Your insights and contributions will help shape this proposal. _Props to [@poliuk](https://profiles.wordpress.org/poliuk/), [@luisherranz](https://profiles.wordpress.org/luisherranz/), [@czapla](https://profiles.wordpress.org/czapla/), and [@greenshady](https://profiles.wordpress.org/greenshady/) for the review and help to shape this post. _ [#block-api](https://make.wordpress.org/core/tag/block-api/), [#block-developer-experience](https://make.wordpress.org/core/tag/block-developer-experience/), [#gutenberg](https://make.wordpress.org/core/tag/gutenberg/), [#interactivity-api](https://make.wordpress.org/core/tag/interactivity-api/) [ ](https://profiles.wordpress.org/santosguillamot/) [Mario Santos](https://profiles.wordpress.org/santosguillamot/) 6:49 pm _on_ March 30, 2023 Tags: block-api, [block-developer-experience ( 5 )](https://make.wordpress.org/core/tag/block-developer-experience/), [gutenberg ( 538 )](https://make.wordpress.org/core/tag/gutenberg/), [interactivity API ( 11 )](https://make.wordpress.org/core/tag/interactivity-api/) # 󠀁[Proposal: The Interactivity API – A better developer experience in building interactive blocks](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/)󠁿 What if effortlessly creating performant, fluid, and idiomatic frontend interactivity on blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.- based WordPress sites was possible? Imagine plugins providing interactions like “ heart this post” or “add to cart” without page reloads. Picture instant search, commenting, and native full-page transitions as best-in-class built-ins without complex scaffolding or external tools. Envision achieving this in any block theme by default without sacrificing PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher server rendering and the pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress. org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) or can be cost-based plugin from a third-party. ecosystem for a JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. runtime. Visualize block developers easily declaring and extending such behaviors in a way that is immediately familiar and compatible with the block ecosystem. That’s what we, the contributors involved in this project, aim to explore and unlock with the **Interactivity APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.**. The demo below shows some of this power and flexibility in action. [Live site demo](https://wpmovies.dev/) / [WP Movies GitHub](https://github.com/wordpress/wp-movies-demo) GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. [https://wordpress.org/gutenberg/](https://wordpress.org/gutenberg/) has evolved a lot over the past few years, though most of the improvements have focused on the block developer experience within the block editor. Today, we’d like to update you on **the Interactivity API, which aims to be a standard way to allow developers to add interactivity to the frontend of their blocks.** Your feedback will be highly appreciated to help shape its next iteration. _Here’s some _[_background reading on the Interactivity API_](https://make.wordpress.org/core/2023/01/11/update-on-the-work-to-make-building-interactive-blocks-easier/)_._ A couple of important notes before diving in: * The Interactivity API is for the frontend of blocks, not for the block editor. This means the API is not expected to be used inside the `edit` function. It’s a way to create interactive user interfaces for your site visitors. Having said that, we’d like to explore whether some directives could be reused across the frontend and the editor to unify the whole block developer experience. * **This is still experimental.** Functionalities are missing, documentation is scarce, and the final API may look different. The API’s design is open to debate, and any feedback is key to ensuring the Interactivity API accounts for the entirety of WordPress’ diverse needs and requirements. ### Table of contents * [API Goals](https://make.wordpress.org/core/tag/block-api/?output_format=md#api-goals) * [What’s being proposed?](https://make.wordpress.org/core/tag/block-api/?output_format=md#whats-being-proposed) * [How to create interactive blocks using this API](https://make.wordpress.org/core/tag/block-api/?output_format=md#how-to-create-interactive-blocks) * [How can users learn more and keep track of the API?](https://make.wordpress.org/core/tag/block-api/?output_format=md#how-can-users-learn-more) * [Next steps](https://make.wordpress.org/core/tag/block-api/?output_format=md#next-steps) * [FAQ](https://make.wordpress.org/core/tag/block-api/?output_format=md#faq) ## API Goals The main goal of the Interactivity API is to **provide a standard and simple way to handle the frontend interactivity of Gutenberg blocks**. A standard makes it **easier for developers to create rich, interactive user experiences**, from simple cases like counters or popups to more complex features like instant page navigation, instant search, or carts and checkouts. All these user experiences are technically possible right now without the Interactivity API. However, the more complex the user experience and the more blocks interact with each other, the harder it becomes for developers to build and maintain sites. There are a lot of challenges they have to figure out themselves. The API aims to provide out-of-the-box means for supporting these kinds of interactions. To address this challenge, before researching different approaches, some requirements/ goals for the API were defined: * **Block-first and PHP-first**: The API must work well with PHP and the current block system, including dynamic blocks, widely extended in WordPress. It must support server-side rendering. Server-rendered HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. and client-hydrated HTML must be exactly the same. This is important for SEO and the user experience. * **Backward compatible**: The API must be compatible with WordPress hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same., which could, for example, modify server-rendered HTML. It must also be compatible with internationalization and existing JS libraries on the site (such as jQuery). * **Optional and gradual adoption**: Related to the previous point, the API must remain optional. It should be possible to adopt it gradually, meaning that interactive blocks not using this API can coexist with those using it. * **Declarative and reactive**: The API must use declarative code, listen to changes in the data, and update only the parts of the DOM that depend on that data. * **Performant**: The runtime must be fast and lightweight to ensure the best user experience. * **ExtensibleExtensible This is the ability to add additional functionality to the code. Plugins extend the WordPress core software.**: In the same way WordPress focuses on extensibility, this new system must provide extensibility patterns to cover most use cases. * **Atomic and composable**: Having small reusable parts that can be combined to create more complex systems is required to create flexible and scalable solutions. * **Compatible with the existing block development tooling:** The API must be integrated with the existing block-building tools without requiring additional tooling or configuration by the developer. Apart from all these requirements, integrating **client-side navigation** on top of any solution should be easy and performant. Client-side navigation is the process of navigating between site pages without reloading the entire page, which is one of the most impressive user experiences demanded by web developers. For that reason, this functionality should be compatible with this new system. ## What’s being proposed? The Interactivity API **is a standard system of directives, based on declarative code, for adding frontend interactivity to blocks**. **Directives extend HTML with special attributes** that tell the Interactivity API to attach a specified behavior to a DOM element or even to transform it. For those familiar with [Alpine.js](https://alpinejs.dev/), it’s a similar approach but explicitly designed to work seamlessly with WordPress. ### Why directives? Directives are the result of deep [research into different possibilities and approaches](https://make.wordpress.org/core/tag/block-api/?output_format=md#approaches-considered). We’ve found that this design covers the requirements most effectively. **Block-first and PHP-friendly** The API is designed for the world of blocks and takes WordPress history of being closely attached to web standards to heart. As directives are added to the HTML, they work great with dynamic blocks and PHP._Dynamic block example_ ```notranslate

This element is now visible!

``` As you can see, directives like `data-wp-on--click` or `data-wp-show` are added as custom HTML attributes. WordPress can process this HTML on the server, handling the directives’ logic and creating the appropriate markup. **Backward compatible** As the Interactivity API works perfectly with server-side rendering, you can use all the WordPress APIs, including: * **WordPress filters and actions**: You can keep using WordPress hooks to modify the HTML or even to modify directives. Additionally, existing hooks will keep working as expected. * **CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. Translationtranslation The process (or result) of changing text, words, and display formatting to support another language. Also see [localization](https://make.wordpress.org/core/tag/block-api/?output_format=md#l10n), [internationalization](https://make.wordpress.org/core/tag/block-api/?output_format=md#i18n). API**: e.g. `[__()](https://developer.wordpress.org/reference/functions/__/)` and `[_e()](https://developer.wordpress.org/reference/functions/_e/)`. You can use it to translate the text in the HTML (as you normally would) and even use those APIs on the server side of your directives.  **Optional and gradual adoption** The Interactivity API pipeline promotes **progressive enhancementenhancement Enhancements are simple improvements to WordPress, such as the addition of a hook, a new feature, or an improvement to an existing feature.** by building on top of WordPress’s solid foundation and patterns. It was carefully designed not to force any use cases to pay for the costs of other use cases. For example, blocks with directives can coexist with other (interactive or non-interactive) blocks. This means that if there are other blocks on the page using other frameworks like jQuery, everything will work as expected. **Declarative and reactive** The Interactivity API follows an approach similar to other popular JS frameworks by separating state, actions, and callbacks and defining them declaratively. Why declaratively? Declarative code describes **what** a program should do, while imperative code describes** how** the program should do it. Using a declarative approach, the UIUI User interface automatically updates in response to changes in the underlying data. With an imperative approach, you must manually update the UI whenever the data changes. Compare the two code examples: _Imperative code_ ```notranslate

This element is now visible!

``` _Declarative code_ This is the same use case shared above but serves as an example of declarative code using this new system. The JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. [https://www.javascript.com](https://www.javascript.com/) logic is defined in the `view.js` file of the block, and add the directives to the markup in the `render.php` . ```notranslate // view.js file import { store, getContext } from "@wordpress/interactivity"; store( 'wpmovies', { actions: { toggle: () => { const context = getContext(); context.isOpen = !context.isOpen; }, }, }); ``` ```notranslate

This element is now visible!

``` Don’t worry if you don’t fully understand this example yet. It will be explained in detail later in the post. Using imperative code may be easier when creating _simple_ user experiences, but it becomes much more difficult as blocks become more complex. The Interactivity API must cover all use cases, from the simplest to the most challenging. That’s why a declarative approach using directives better fits the Interactivity API. **Performant** The API has been designed to be as performant as possible: * **The runtime code needed for the directives is just ~10 KB**, and it only needs to be loaded once for all the blocks. * **It only loads the directives needed** by the blocks present on the page. For example, if no blocks are using `data-wp-show`, the code for this directive won’t be loaded. * **The scripts will load without blocking the page rendering**. * There are ongoing explorations about the possibility of **delaying the scripts loading once the block is in the viewport**. This way, the initial load would be optimized without affecting the user experience. **Extensible** Directives can be added, removed, or modified directly from the HTML. For example, users could use the [`render_block` filter](https://developer.wordpress.org/reference/hooks/render_block/) to modify the HTML and its behavior. In addition to using built-in directives, users can create custom directives to add any custom behaviors to their HTML. **Atomic and composable** Each directive controls a small part of the DOM, and you can combine multiple directives to create rich, interactive user experiences. **Compatible with the existing block development tooling** Using built-in directives does not require a build step and only requires a small runtime. A build step is necessary only when creating custom directives that return JSX. For such use cases, the API works out of the box with common block-building tools like `[wp-scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/)`. **Client-side navigation** The Interactivity API comes with built-in primitives for adding client-side navigation to your site. This functionality is completely optional, but it opens the possibility to create these user experiences without having to opt out of the WordPress rendering system. It also pairs very well with the [View Transitions API](https://developer.chrome.com/docs/web-platform/view-transitions/) allowing developers to animate page transitions easily. ### Why a standard? Blocks using the Interactivity API and interactive blocks using other approaches like jQuery can coexist, and everything will work as expected. However, the Interactivity API comes with some benefits for your interactive blocks: * **Blocks can communicate with each other easily**. With a standard, this communication is handled by default. When different blocks use different approaches to frontend interactivity, inter-block communication becomes more complex and almost impossible when separate developers create blocks. * **Composability and compatibility**: You can combine interactive blocks, and nest them in structures with defined behaviors. Thanks to following the same standard, they are fully cross-compatible. If each block used a different approach to interactivity, they would likely break. * **Fewer KBs will be sent to the browser**. If each plugin author uses a different JS framework, more code will be loaded in the frontend. If all the blocks use the same one, the code is reused. * If all the blocks on a page use this standard,** site-wide features like [client-side navigation](https://make.wordpress.org/core/tag/block-api/?output_format=md#client-side-navigation) can be enabled**. Additionally, with a standard, **WordPress can absorb the maximum amount of complexity from the developer** because it will handle most of what’s needed to create an interactive block. _Complexities absorbed by the standard_ ![Two columns table comparing some aspects with and without a standard. Without a standard, block developers have to take care of everything, while having a standard: - Totally handled by the standard: Tooling, hydration, integrating it with WordPress, SSR of the interactive parts, inter-block communication, and frontend performance. - Partially handled: Security, accessibility, and best practices. - Developer responsibility: Block logic. In the without a standard column, everything is under the developer responsability.](https://make.wordpress.org/core/files/2023/03/standard-graph-542x1024. png) With this absorption, less knowledge is required to create interactive blocks, and developers have fewer decisions to worry about. Additionally, if the community adopts a standard, learning from other interactive blocks would be simpler, which fosters collaboration and code reusability. This should simplify the development process and make it friendlier to less experienced developers. ## How to create interactive blocks using the API It’s important to highlight that **the block creation _workflow_ doesn’t change**. Until now, WordPress has been intentionally unopinionated about the different solutions used on the frontend of blocks. The Interactivity API changes that. It adds **a new standard way to easily add frontend interactivity to blocks** while the APIs handling the Block Editor remain the same. To add interactivity to blocks using the Interactivity API, developers would need to: 1. Add directives to the markup to add specific behavior to the block. 2. If needed, create a store with the logic (state, actions, or callbacks) needed for interactivity. Blocks using only directives with self-sufficient logic like` data-wp-link`, don’t need this step. Before explaining each step in more detail, let’s return to our example: a button that shows and hides some text. We’ll also add logic to send a message in the console whenever the button is hidden/revealed. _**Add directives**_ Directives are added to the markup of your block. In the `render.php` file (for dynamic blocks) or the `save.js` file (for static blocks). ```notranslate

This element is now visible!

``` In this example, the directive `data-wp-context` is used to define some local state(`" isOpen": false`) that will be available to that HTML node and all its children. All the actions and callbacks used in those nodes can access that data. Knowing that, other directives like `data-wp-on--click` can trigger actions and callbacks reading that context. **_Create the store_** In this part, the logic (actions and callbacks) called by the directives is defined. The store is created in the `view.js` file of each block. Although it works at a block level right now, the possibility of sharing code that multiple blocks need will be investigated as well. ```notranslate // view.js import { store, getContext } from "@wordpress/interactivity"; store( 'wpmovies', { actions: { toggle: () => { const context = getContext(); context.isOpen = !context.isOpen; }, }, callbacks: { logIsOpen: () => { const context = getContext(); // Log the value of `isOpen` each time it changes. console.log(`Is open: ${context.isOpen}`); }, }, }); ``` For those familiar with ReactReact React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. [https://reactjs.org](https://reactjs.org/), this would be an equivalent React component: ```notranslate const Comp = () => { const [isOpen, setIsOpen] = useState(false); useEffect(() => { // Log the value of `isOpen` each time it changes. console.log(`Is Open: ${isOpen}`); }, [isOpen]); const toggle = () => { setIsOpen(!isOpen); }; return (
{isOpen &&

This element is visible!

}
); }; ``` Let’s take a look at each step in detail: ### 1. Add the directives Directives are custom HTML attributes whose value can contain options or references to the store. Let’s return to our previous example: _Dynamic block example_ ```notranslate // render.php
data-wp-interactive='{ "namespace": "wpmovies" }' data-wp-context='{ "isOpen": false }' data-wp-watch="callbacks.logIsOpen" >

This element is now visible!

``` This is how it would work in a static block: _Static block example_ ```notranslate // save.js const save = () => { return `

This element is now visible!

`; }; ``` The example above uses directives like `wp-show` and `wp-on` to add interactivity to the HTML. Below is the initial list of core directives planned, which aims to cover the most common use cases for adding interactivity. It has been inspired by other frameworks like Alpine, VueVue Vue (pronounced /vjuː/, like view) is a progressive framework for building user interfaces. [https://vuejs.org/](https://vuejs.org/)., or Svelte: * `wp-context` provides **local** state available to a specific HTML node and its children. * `wp-on` runs code on dispatched DOM events like `click` or `keyup`. The format of this directive is `data-wp-on--[event]`, like `data-wp-on--click` or `data- wp-on--keyup`. * `wp-show` shows and hides elements depending on the state or context. * `wp-each` creates DOM elements by iterating through a list. * `wp-bind` allows setting HTML attributes on elements. * `wp-class` adds or removes a class to an HTML element, depending on its value. * `wp-style` adds or removes inline style to an HTML element, depending on its value. * `wp-text` sets the inner content of an HTML element. * `wp-html` sets the innerHTML property of an HTML element. * `wp-slot` / `wp-fill` moves snippets of HTML from one place (fills) to another( slots). * `wp-watch` runs an expression when the node is created and runs it again when the state or context changes. * `wp-init` runs an expression only when the node is created. * `wp-error` captures errors in other interactive blocks. Please bear in mind that this list may vary, and not all these core directives have been implemented yet. Additionally, the API is extensible: **anyone can create their own directives if needed**. An important feature is that, when needed, **directives support server-side rendering in PHP**. This results in a better user experience and better SEO. This is usually taken for granted with WordPress but, when using modern frameworks like React to add interactivity to blocks, it is common to show empty content until client-side JavaScript updates the HTML. ### 2. Create the store The store contains the reactive state and the actions and callbacks that modify it. * **State:** Defines data available to the HTML nodes of the page. It is important to differentiate between two ways to define the data: - **Global state**:  It is defined using the `store()` function, and the data is available to all the HTML nodes of the page. - **Context/Local State**: It is defined using the `data-wp-context` directive in an HTML node, and the data is available to that HTML node and its children. * **Actions**: Usually triggered by the `data-wp-on` directive (using event listeners) or other actions. * **Callbacks**: Automatically react to state changes. Usually triggered by `data- wp-callback` or `data-wp-init` directives. Returning to our example, this could be a simple store in one block: ```notranslate // view.js import { store, getContext } from "@wordpress/interactivity"; store( 'wpmovies', { actions: { toggle: () => { const context = getContext(); context.isOpen = !context.isOpen; }, }, callbacks: { logIsOpen: () => { const context = getContext(); // Log the value of `isOpen` each time it changes. console.log(`Is open: ${context.isOpen}`); }, }, }); ``` In this specific case, only actions and callbacks are defined, but some `state` could also be included. For example, you could define the `state` in another block to create a list with your “Favorite movies”. It might look something like this: ```notranslate // view.js - A favorite movies block import { store, getContext } from '@wordpress/interactivity'; const { state } = store( 'wpmovies', { state: { favoriteMovies: [], }, actions: { addMovie: () => { const context = getContext(); // We assume that there is a `wp-context` directive // on the block which provides the item ID. state.favoriteMovies.push(context.item.id); }, clearFavoriteMovies: () => { state.favoriteMovies = []; }, }, }); ``` **Note: **The `store` function will automatically merge the store definitions from all the blocks using `store` into a single reactive object. This way, you can use the global state defined in other blocks. #### Initializing the store on the server with `wp_initial_state()` The state can also be _initialized_ on the server using the `wp_initial_state()` function. You would typically do this in the `render.php` file of your block (the` render.php` templates were [introduced](https://make.wordpress.org/core/2022/10/12/block-api-changes-in-wordpress-6-1/) in WordPress 6.1). Initializing your state on the server allows you to populate it with some data from the server without worrying about serializing that data or making additional API requests. The store defined on the server with `wp_initial_state()` gets merged with the stores defined in the `view.js` files. For example, the “Favorite movies” block from above could initialize its store on the server like this: ```notranslate // render.php wp_initial_state( 'wpmovies', array( favoriteMovies => get_favorite_movies(), ) ); ``` And then its `view.js` file would be simplified to: ```notranslate // view.js - A favorite movies block import { store, getContext } from '@wordpress/interactivity'; const { state } = store( 'wpmovies', { actions: { addMovie: () => { const context = getContext(); // We assume that there is a `wp-context` directive // on the block which provides the item ID. state.favoriteMovies.push(context.item.id); }, clearFavoriteMovies: () => { state.favoriteMovies = []; }, }, }); ``` Initializing the store in the server also allows you to use any WordPress API. For example, you could use the Core Translation API to translate part of your state: ```notranslate // render.php wp_initial_state( 'wpmovies', array( "favoriteMovies" => array( "1" => array( "id" => "123-abc", "movieName" => __("someMovieName", "textdomain") ), ), ) ); ``` #### References When creating a directive, you might notice that its value is a string pointing to a specific state, an action, or a callback. For instance, in the example that we’ve been using in this post, the value of the `data-wp-on--click` directive was` actions.toggle`, and the value of `data-wp-watch` was `callbacks.logIsOpen`. Those values are **references** to a particular property in the store. They are wired to the directives automatically so that each directive “knows” what `actions. toggle` refers to without any additional configuration. When a directive is evaluated, the reference callback receives an object with: * The `store` containing the `state`, `actions` and `callbacks`. * The context (an object containing the context defined in all the `wp-context` ancestors). * The reference to the DOM element on which the directive was defined (a `ref`). * Other properties relevant to the directive. For example, the `data-wp-on--click` directive also receives the instance of the [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent) triggered by the user. ```notranslate import { store, getContext, getElement } from "@wordpress/interactivity" const { state } = store( 'wpmovies', { state: { theme: false, }, actions: { toggle: ( event ) => { console.log(state); // `{ "theme": false }` const context = getContext(); console.log(context); // `{ "isOpen": true }` const { ref } = getElement(); console.log(ref); // The DOM element console.log(event); // The Event object if using the `data-wp-on` } } }) ``` This approach enables some functionalities that make directives flexible and powerful: * Actions and callbacks can read and modify the state and the context. - _Movie Tabs_ block reads and modifies [the context](https://github.com/WordPress/wp-movies-demo/blob/c4ca64bc6f89fa7f78786e71fc1fd82c4f8c0085/src/blocks/interactive/movie-tabs/view.js#L11-L19). - _Video Player_ block reads and modifies [the state](https://github.com/WordPress/wp-movies-demo/blob/c4ca64bc6f89fa7f78786e71fc1fd82c4f8c0085/src/blocks/interactive/video-player/view.js#L10-L22). * Actions and state in blocks can be accessed by other blocks: - _Movie Trailer Button_ block uses[ `action.wpmovies.setVideo`](https://github.com/WordPress/wp-movies-demo/blob/c4ca64bc6f89fa7f78786e71fc1fd82c4f8c0085/src/blocks/interactive/movie-trailer-button/render.php#L19), which is [defined in the _Video Player_ block](https://github.com/WordPress/wp-movies-demo/blob/c4ca64bc6f89fa7f78786e71fc1fd82c4f8c0085/src/blocks/interactive/video-player/view.js#L15). * Actions and callbacks can do anything a regular JavaScript function can do, like access the DOM or make API requests. * Callbacks automatically react to state changes. ## How can users learn more and keep track of the API? If you are interested in this proposal, let us know in the comments or the [Interactivity API GitHub repo](https://github.com/WordPress/block-interactivity-experiments). Your feedback is highly appreciated. If you want to learn more about the Interactivity API, here is a list of relevant links with more information: * [GitHub repo](https://github.com/WordPress/block-interactivity-experiments): This is where most aspects are discussed and a way to follow the development process. Feel free to open any [issue](https://github.com/WordPress/block-interactivity-experiments/issues), [discussion](https://github.com/WordPress/block-interactivity-experiments/discussions), or [pull request](https://github.com/WordPress/block-interactivity-experiments/pulls). * [Movies demo repo](https://github.com/WordPress/wp-movies-demo): An example with some interactive blocks and user experiences. If you are interested in the code or even reproducing it locally, the information is gathered [here](https://github.com/WordPress/wp-movies-demo/blob/main/README.md). There will be more resources in the future, including technical documentation, to explain everything in more detail. ## Next steps **There will be two sessions on April 17th, 2023 ([one at 08:00UTC](https://www.meetup.com/learn-wordpress-online-workshops/events/292575913/) and [another at 17:00UTC](https://www.meetup.com/learn-wordpress-online-workshops/events/292575942/)) featuring a live product demo followed by a Q&A**. The specifics for each session will be announced on the Make Core blogblog (versus network, site). If you’re interested in the Interactivity API, have any related questions, or want to provide feedback, feel free to join us. For those who cannot attend or prefer to share feedback in writing, comment on this post. Additionally, the session will be recorded and posted it here. _EDIT: **These are the links to both sessions**, where the Interactivity API is explained in more detail and answered some questions:_ * _[First session](https://wordpress.tv/2023/04/17/developer-hours-interactivity-api-apac-emea/): Hosted by Michael Burridge and led by Mario Santos and Luis Herranz._ * _[Second session](https://wordpress.tv/2023/04/18/developer-hours-introduction-to-the-interactivity-api/): Hosted by Ryan Welcher and led by Michal Czaplinski_ With this in mind, these are the next steps for the Interactivity API: * Gather and address the feedback received in the live session and this post. * Keep developing the API, incorporating the feedback. * Work on more technical documentation to explain in detail how the Interactivity API works. * Once there is enough feedback and the API feels confident enough, **the intent is to add the API as an experimental feature to Gutenberg so block authors can start building with it **(with the eventual goal of including it in Core). ## FAQ #### How does the Interactivity API work under the hood? Its three main components are: * [Preact](https://preactjs.com/) combined with [Preact Signals](https://preactjs.com/guide/v10/signals/) for hydration, client logic, and client-side navigation. * HTML [Directives](https://make.wordpress.org/core/tag/block-api/?output_format=md#add-directives) that can be understood by both the client and server. * Server-side logic, handled by the [HTML_Tag_Processor](https://make.wordpress.org/core/2023/03/07/introducing-the-html-api-in-wordpress-6-2/). There will be more technical documentation to explain the API in more detail in the future. In the meantime, please share any questions in the comments or on the [GitHub repo](https://github.com/WordPress/block-interactivity-experiments/discussions). #### Why did you choose Preact to build the directives system? Why not React or another JavaScript framework? Preact has a number of advantages over React and other JavaScript frameworks like Vue, Svelte, or Solid in the context of the frontend (which is the focus of the Interactivity API): * It’s small: 8kB, including [hooks](https://preactjs.com/guide/v10/hooks/) and [signals](https://preactjs.com/blog/introducing-signals/). * It’s battle-tested. * It’s performant (even more when used with signals). * It’s compatible with React (through `preact/compat`, useful to share the same Editor components for some use cases where SSR is not important, and the components are very complex, like an e-commerce cart and checkout, for example). * It’s HTML-friendly (unlike React). * It gives us DOM diffing out of the box. * It’s **extremely extensible** through their Option Hooks. They use that extensibility for the hooks (`preact/hooks`), compatibility with React (`preact/compat`) and their signals (`@preact/signals`). Basically, everything but the DOM diffing algorithm. * Its core team has been great and very helpful. They are also interested in enhancing this “island-based” usage of Preact. #### Is Gutenberg going to move from React to Preact since the Interactivity API uses it? No. At the moment, there are no plans to make that transition. The requirements and advantages of the editor, as a fully interactive application, are quite different. Preact _does_ have a [`@preact/compat`](https://preactjs.com/guide/v10/switching-to-preact/) package that enables full compatibility with the React ecosystem, and many large web applications use it. However, using Preact in the block editor would **not** offer advantages like it does on the frontend in the Interactivity API. #### What approaches have been considered instead of using directives? Many alternative approaches were considered. Here’s a brief summary of some of them: **_React and other JavaScript frameworks_** React was considered first because Gutenberg developers are familiar with it. Other popular JS frameworks like Svelte, Vue.js, or Angular were also considered, but none of them (including React) are PHP-friendly or compatible with WordPress hooks or internationalization. See [above](https://make.wordpress.org/core/tag/block-api/?output_format=md#why-preact) for a longer explanation. **_Alpine.js_** Alpine.js is a great framework, and it inspired a lot of functionality in the Interactivity API. However, it doesn’t support server-side rendering of its [directives](https://github.com/alpinejs/alpine/tree/d7f9d641f7a763c56c598d118bd189a406a22383/packages/docs/src/en/directives), and having a similar system tailored for WordPress blocks has many benefits. **_Plain JavaScript_** See [the answer](https://make.wordpress.org/core/tag/block-api/?output_format=md#why-not-jquery) below.  **_Template DSL_** The possibility of creating a [DSL](https://en.wikipedia.org/wiki/Domain-specific_language) for writing interactive templates was also researched. The code written in that Template DSL would then be compiled into both JavaScript and PHP. However, creating a production-grade Template compiler is complex and would be a large and risky investment of effort. This approach is still being considered for the future, with the directives serving as a compilation target. #### Why should I, as a block developer, use the Interactivity API rather than React? Using React on the frontend doesn’t work smoothly with server rendering in PHP. Every approach that uses React to render blocks has to load content using client- side JavaScript. If you only render your blocks on the client, it typically results in a poor user experience because the user stares at empty placeholders and spinners while waiting for content to load. Now, it’s possible to server-render a block in PHP **and** use React to render the same block on the frontend. However, this results in a poor developer experience because the logic has to be duplicated across the PHP and React parts. Not only that, but you have now exposed yourself to subtle bugs caused by WordPress hooks! Imagine installing a third-party plugin with a hook (filterFilter Filters are one of the two types of Hooks [https://codex.wordpress.org/Plugin_API/Hooks](https://codex.wordpress.org/Plugin_API/Hooks). They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output.) that modifies the server-rendered HTML. Let’s say this filter adds a single CSSCSS Cascading Style Sheets. class to your block’s HTML. That CSS class will be present in the server-rendered markup. On the frontend, your block will render again in React, but now the content will **not** include that CSS class because there is no way to apply WordPress hooks to React-rendered content! On the other hand, the Interactivity API is designed to work perfectly with WordPress hooks because directives enhance the server-rendered HTML with behaviors. This also means it works out of the box with WordPress backend APIs like i18ni18n Internationalization, or the act of writing and preparing code to be fully translatable into other languages. Also see [localization](https://make.wordpress.org/core/tag/block-api/?output_format=md#l10n). Often written with a lowercase i so it is not confused with a lowercase L or the numeral 1. Often an acquired skill.. To summarize, using the Interactivity API rather than just using React comes with these benefits: * If you use React, your interactive blocks must generate the same markup on the client as they do on the server in PHP. Using the Interactivity API, there is no such requirement as directives are added to server-rendered HTML. * The Interactivity API is PHP-friendlier. It works out of the box with WordPress hooks or other server functionalities such as internationalization. For example, with React, you can’t know which hooks are applied on the server, and their modifications would be overwritten after hydration. * All the [benefits of using a standard](https://make.wordpress.org/core/tag/block-api/?output_format=md#why-a-standard). #### What are the benefits of Interactivity API over just using jQuery or vanilla JavaScript? The main difference is that the Interactivity API is **declarative and reactive**, so writing and maintaining complex interactive experiences should become way easier. Additionally, it has been **specially designed to work with blocks**, providing a standard that comes with the benefits mentioned above, like inter-block communication, compatibility, or site-wide features such as client-side navigation. Finally, comparing it with jQuery, **the Interactivity API runtime is ~10kb**, which is much more lightweight. Actually, there is an ongoing effort to remove heavy frameworks like jQuery across the WordPress ecosystem, and this would help in this regard. #### Do I need to know React, PHP, and this new Interactivity API? If you want to add frontend interactivity to your blocks using this API, the short answer is yes. If your block is not interactive, the block creation workflow will remain exactly the same. As mentioned in the post, this API only adds a new standard way to easily add frontend interactivity to blocks, which didn’t exist until now. This means that you will still need to use React to handle the editor part of your blocks. In the future, we’d like to explore the possibility of expanding the usage of directives to unify the developer experience among the Editor as well. On the other hand, if you want to create an interactive block, with the Interactivity API you don’t have to deal with complex topics like tooling, integration with WordPress, inter-block communication, or the server-side rendering of the interactive parts. #### Does this mean I must migrate all my interactive blocks to use this API? No. Blocks outside the Interactivity API can coexist with blocks using it. However, as explained above, keep in mind that there are some benefits for blocks that use the API: * **Blocks can communicate with each other easily**. With a standard, this communication is handled by default. When different blocks use different approaches to frontend interactivity, inter-block communication becomes more complex and gets almost impossible when separate developers create blocks. * **Composability and compatibility**: You can combine interactive blocks, nest them in structures with defined behaviors, and, thanks to following the same standard, they are fully cross-compatible. If each block were to use a different approach to interactivity, they would likely break. * **Fewer KBs will be sent to the browser**. If each plugin author uses a different JS framework, more code will be loaded in the frontend. If all the blocks use the same one, the code is reused. * If all the blocks on a page use this standard,** site-wide features like [client-side navigation](https://make.wordpress.org/core/tag/block-api/?output_format=md#client-side-navigation) can be enabled**. #### What are the performance implications of using this API? Is it worth loading the Interactivity API for very simple use cases? The API has been designed with performance in mind, so it shouldn’t be a problem: * **The runtime code needed for the directives is just ~10 KB**, and it only needs to be loaded once for all the blocks. * **It only loads the directives needed** by the blocks present on the page. For example, if no blocks use `data-wp-show`, that directive won’t be loaded. * **All the scripts that belong to the Interactivity API (including the `view.js` files) will load without blocking the page rendering**. * There are ongoing explorations about the possibility of **delaying the scripts loading once the block is in the viewport**. This way, the initial load would be optimized without affecting the user experience. #### Can I use directives in the block editor? No. Right now, directives only work in the frontend of blocks. However, it’ll be investigated whether some directives (and also your custom directives) could be reused across the frontend and the editor. It’s worth emphasizing that the realities of the editor application and the frontend of a website are very different, particularly around the interactivity they afford. It needs to be ensured that the right tools are built for the right context. An interesting area to explore further would be to expose directives in the editor so users and builders can use them to attach behaviors to their sites on demand. #### Does it work with the Core Translation API? It does! As the Interactivity API works perfectly with server-side rendering, you can use all the WordPress APIs including `[__()](https://developer.wordpress.org/reference/functions/__/)` and `[_e()](https://developer.wordpress.org/reference/functions/_e/)`. You can use it to translate the text in the HTML (as you normally would) and even use it inside the store when using `wp_initial_state()` on the server side. It might look something like this: ```notranslate // render.php wp_initial_state( 'wpmovies', array( "favoriteMovies" => array( "1" => array( "id" => "123-abc", "movieName" => __("someMovieName", "textdomain") ), ), ) ); ``` #### How can I test it? Before testing, bear in mind that the Interactivity API is still experimental and very likely to change before an official release. There are still missing functionalities that may break your site, and the API hasn’t been documented yet properly. If you plan to use it, do so at your own risk. If you want to test the Interactivity API, you can install [the latest version of the plugin](https://github.com/WordPress/block-interactivity-experiments/releases/latest/download/block-interactivity-experiments.zip) on your site. Note that it requires the latest version of Gutenberg to work. Once installed, you can start creating interactive blocks using the API. If you prefer to test the Interactivity API in a demo site with some interactive blocks already in place, you can look at the[ WP Movies demo](https://github.com/WordPress/wp-movies-demo). #### How can interactive blocks update/save the state on the server? It is still an active area of research, but is on the roadmap for the Interactivity API. For example, there’s an ongoing experiment to create an[ interactive version of the Comments Form block](https://github.com/WordPress/gutenberg/pull/49305#issuecomment-1487141538) that can persist comments on the site and refresh itself without a full page reload. #### Is it going to be a plugin? Or will it be part of Gutenberg/Core? Although it is now distributed as a plugin, it aims to be added as an experimental feature to Gutenberg. The goal is to include it in Core once enough feedback has been gathered, and it’s clear that it’s the right direction. #### I’m concerned about XSS; can JavaScript be injected into directives? No. The Interactivity API only allows for [References](https://make.wordpress.org/core/tag/block-api/?output_format=md#references) to be passed as values to the directives. This way, there is no need to `eval()` full JavaScript expressions, so it’s not possible to perform XSS attacks. #### Does this work with CSP? Yes. The Interactivity API does not use [`eval()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval) or the [`Function()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/Function) constructor, so it doesn’t violate the [`unsafe-eval`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#unsafe_keyword_values) content security policy. It is also designed to work with any custom content security policy. #### Can you use directives to make AJAX/REST-API requests? Sure. Actions and callbacks called by directives can do anything a JavaScript function can, including making API requests. --- As mentioned during the post, **it’d be great to hear your thoughts and new ideas in the [GitHub repo](https://github.com/WordPress/block-interactivity-experiments/discussions)**. Special props to [@czapla](https://profiles.wordpress.org/czapla/) , who coauthored this blog post with me from the start, and to [@kristastevens](https://profiles.wordpress.org/kristastevens/) for her invaluable help in shaping the document and ensuring everything was cohesive. And also thanks to [@luisherranz](https://profiles.wordpress.org/luisherranz/), [@bernhard-reiter](https://profiles.wordpress.org/bernhard-reiter/), [@poliuk](https://profiles.wordpress.org/poliuk/), [@darerodz](https://profiles.wordpress.org/darerodz/), [@cbravobernal](https://profiles.wordpress.org/cbravobernal/), [@dmsnell](https://profiles.wordpress.org/dmsnell/), [@gziolo](https://profiles.wordpress.org/gziolo/), [@zieladam](https://profiles.wordpress.org/zieladam/), [@artemiosans](https://profiles.wordpress.org/artemiosans/), [@matveb](https://profiles.wordpress.org/matveb/), [@richtabor](https://profiles.wordpress.org/richtabor/), [@annezazu](https://profiles.wordpress.org/annezazu/), [@isabel_brison](https://profiles.wordpress.org/isabel_brison/), [@azaozz](https://profiles.wordpress.org/azaozz/), [@westonruter](https://profiles.wordpress.org/westonruter/), [@flixos90](https://profiles.wordpress.org/flixos90/), [@fabiankaegy](https://profiles.wordpress.org/fabiankaegy/), [@tweetythierry](https://profiles.wordpress.org/tweetythierry/), [@mamaduka](https://profiles.wordpress.org/mamaduka/), [@kadamwhite](https://profiles.wordpress.org/kadamwhite/), [@alexstine](https://profiles.wordpress.org/alexstine/), [@andraganescu](https://profiles.wordpress.org/andraganescu/), [@greenshady](https://profiles.wordpress.org/greenshady/), [@juanmaguitar](https://profiles.wordpress.org/juanmaguitar/), [@mburridge](https://profiles.wordpress.org/mburridge/), [@welcher](https://profiles.wordpress.org/welcher/), [@bph](https://profiles.wordpress.org/bph/), [@griffbrad](https://profiles.wordpress.org/griffbrad/), [@jsnajdr](https://profiles.wordpress.org/jsnajdr/), [@youknowriad](https://profiles.wordpress.org/youknowriad/), [@mcsf](https://profiles.wordpress.org/mcsf/), [@nerrad](https://profiles.wordpress.org/nerrad/), [@assassinateur](https://profiles.wordpress.org/assassinateur/), [@yscik8](https://profiles.wordpress.org/yscik8/), [@jorbin](https://profiles.wordpress.org/jorbin/), and [@davidbaumwald](https://profiles.wordpress.org/davidbaumwald/) for all the feedback about the API and reviewing and helping shape this post! [#interactivity-api](https://make.wordpress.org/core/tag/interactivity-api/), [#block-developer-experience](https://make.wordpress.org/core/tag/block-developer-experience/), [#block-api](https://make.wordpress.org/core/tag/block-api/), [#gutenberg](https://make.wordpress.org/core/tag/gutenberg/)