elliott richmond

TL;DR:

WordPress 6.5 will come shipped with the new Interactivity API, but…

What is the Interactivity API?
The WordPress Interactivity API is a lightweight JavaScript library based on preactjs, aiming to standardise how developers manipulate HTML in a reactive way.

Traditionally, developers would use a multitude of different ways to achieve similar thing using vanilla JavaScript.

Over time, this becomes incredibly cumbersome and difficult to manage as your application grows with new features and functionality in an ever growing complex Javascript file.

The Interactivity API aims to simplify this issue.

How does it work?
HTML can be broken down into nodes resembling a tree-like structure, referred to as the Document Object Model or DOM.

Using the Interactivity API, data and information can be passed up and down the branches of the DOM based on user interactions, such as on-click, keyup, scroll, and many other interactive gestures.

Most of the time, this data belongs to one element and can be referred to as a Component.

However, the new Interactivity API will allow developers to share data across multiple components, which can also be associated with core Block references by their namespace.

This paves the way for greater flexibility within the core of using the block editor.

For instance, the Interactivity API is already being used in Image, Search, Query, and Navigation blocks, to name a few.

Why would you use it?
Developers can create rich, interactive user experiences, from creating simple counters or pop-ups to more complex features like shopping carts, dashboards, or even interactive games like Dodge created by Johnathan Bossenger.

To use the Interactivity API in WordPress 6.5, you can create a new block from a template using NPM, or you can activate it on existing blocks by installing the @wordpress/interactivity dependency and adjusting the package & block.json file and including a render.php file.

However, it can get a little trickier to do it this way.

As this is a new feature, I’d personally opt to create a new block from a template.

Using the terminal, you can change directory or CD into your plugins folder and from the Interactive documentation, you can run the following command:

npx @wordpress/create-block@latest my-first-interactive-block --template @wordpress/create-block-interactive-template

This will set you up with a very basic Interactive-ready block.

Don’t forget to activate the plugin and insert the block into a page ready for development.

You will also need to run the command npm start to start a build process and watch the src files of your interactive block.

Once the Interactivity API is enabled, behaviors need to be referenced on HTML elements in the render.php file that is bundled with your interactive block.

These are referred to as directives and are added to HTML elements in the same way other attributes are added to elements.

All directives are prefixed with data-wp- followed by the specific directive, then followed by side effects, state, event handlers, attributes, or content.

For example:
data-wp-interactive="create-block/namespace" to activate a component specifically for your interactive block.

Note that the namespace is unique to the component, and this is the method for accessing shared data from other blocks.

An example of a core block might be:
data-wp-interactive="core/image" or
data-wp-interactive="core/query" or
data-wp-interactive="create-block/to-do-list" etc.

Other directive examples include:
data-wp-context="{ 'user_id': '123’,'name':'elliottrichmond' }" that accepts stringified JSON as a value that includes data that will be used throughout the component.

Or an event directive, for example:
data-wp-on--click="actions.doSomeLogic” to trigger a function on the click event
data-wp-on—keyup="actions.doSomeLogic” to trigger a function on the keyup event
data-wp-on-window--resize=“callbacks.logWidthOrHeight” to trigger a function on the window resized event.

Don’t worry about trying to remember all of these directives, see here for all the currently available Interactive API directives.

At the time of recording this, it’s a mandatory requirement to add the “data-wp-interactive” directive to the parent or root element for the Interactivity API to work up and down the tree of the DOM.

Without it, none of the other directives will work.

That said, there are plans to automatically inject this directive in future releases of WordPress.

In turn, directives connect the context and state properties to a global store object that typically reference ‘actions’ and ‘callbacks’ in a view.js file generated in the Interactive block that re-renders data held in render.php file or effectively in the front-facing part of your website, typically referred to a the user interface.

Check out my practical introduction to the Interactivity API where I creating a Pizza Dough Calculator via my YouTube channel.