WordPress.org
Get WordPress
WordPress.org

WordPress Developer Resources

Interactivity API Reference

Interactivity API Reference

In this article

Back to top

The Interactivity API, introduced in WordPress 6.5, provides a standard way for developers to add interactions to the front end of their blocks. The API is also used in many Core WordPress blocks, including Search, Query, Navigation, and File.

This standard makes it easier for developers to create rich, interactive user experiences, from simple counters or pop-ups to more complex features like instant page navigation, instant search, shopping carts, or checkouts.

Blocks can share data, actions, and callbacks between them. This makes communication between blocks simpler and less error-prone. For example, clicking on an “add to cart” block can seamlessly update a separate “cart” block.

For more information about the genesis of the Interactivity API, check out the original proposal. You can also review the merge announcement, the status update post, and the official Trac ticket.

The Interactivity API is supported by the package @wordpress/interactivity which is bundled in WordPress Core from v6.5

Use the following links to locate the topic you’re interested in. If you have never worked with the Interactivity API before, consider reading through the following resources in the order listed.

To get a deeper understanding of what the Interactivity API is or find answers to questions you may have about this standard, check the following resources:

  • About the Interactivity API: To learn more about the API Goals and the reasoning behind the use of a standard to add interactivity to blocks.
  • Frequently Asked Questions: To find responses to some frequently asked questions about the technology behind and alternatives.

Requirements of the Interactivity API

Interactivity API is included in Core in WordPress 6.5. For versions below, you’ll need Gutenberg 17.5 or higher installed and activated in your WordPress installation.

It’s also important to highlight that the block creation workflow doesn’t change, and all the prerequisites remain the same. These include:

You can start creating interactions once you set up a block development environment and run WordPress 6.5+ (or Gutenberg 17.5+).

Code requirements

Add interactivity to your project

Install the Interactivity API to your project with the following command:

npm install @wordpress/interactivity --save

Import the store into your view.js. Refer to the store documentation for more information.

import { store } from '@wordpress/interactivity';

Add interactivity support to block.json

To indicate that the block supports the Interactivity API features, add "interactivity": true to the supports attribute of the block’s block.json file.

// block.json
"supports": {
    "interactivity": true
},

Refer to the interactivity support property docs to get a more detailed description of this property.

Load Interactivity API JavaScript code with viewScriptModule

The Interactivity API provides the @wordpress/interactivity Script Module. JavaScript using the Interactivity API should be implemented as Script Modules so they can depend on @wordpress/interactivity. Script Modules have been available since WordPress 6.5. Blocks can use viewScriptModule block metadata to enqueue their Script Modules easily:

// block.json
{
   ...
   "viewScriptModule": "file:./view.js"
}

The use of viewScriptModule also requires the --experimental-modules flag for both the build and start scripts of wp-scripts to ensure a proper build of the Script Modules.

// package.json
{
    "scripts": {
        ...
        "build": "wp-scripts build --experimental-modules",
        "start": "wp-scripts start --experimental-modules"
    }

Add wp-interactive directive to a DOM element

To “activate” the Interactivity API in a DOM element (and its children), add the wp-interactive directive to the DOM element in the block’s render.php or save.js files.

<div data-wp-interactive="myPlugin">
    <!-- Interactivity API zone -->
</div>

Refer to the wp-interactive documentation for a more detailed description of this directive.

Docs & Examples

Here you have some more resources to learn/read more about the Interactivity API:

There’s a Tracking Issue opened to ease the coordination of the work related to the Interactivity API Docs: Documentation for the Interactivity API – Tracking Issue #53296

First published

Last updated

Edit article

Improve it on GitHub: Interactivity API Reference