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.

Navigating the Interactivity API docs

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.

• Requirements: Check this section before you start creating your interactive blocks with the Interactivity API.
• Quick Start Guide: Get a custom block using the Interactivity API up and running in less than one minute.
• Tutorial: A first look at the Interactivity API: This article from the WordPress Developer Blog is a great way to get introduced to the Interactivity API.
• Core Concepts: Gain a better understanding of concepts and mental models related to Interactivity API development from this section.
• Directives and Store: To take a deep dive into how the API works internally, the list of Directives, and how the Store works.
• Docs and Examples: Additional resources to learn/read more about the Interactivity API.

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:

• Code Editor
• Node.js development tools
• Local WordPress environment (site)

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.

In 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:

In 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.

Note: If you scaffolded your block using the @wordpress/create-block-interactive-template, this flag is already included in your package.json scripts and no manual configuration is needed.

If you need to add it manually, update your 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:

• WordPress 6.5 Dev Note
• Merge announcement
• Proposal: The Interactivity API – A better developer experience in building interactive blocks
• Interactivity API Discussions, especially the showcase discussions.
• wpmovies.dev demo and its wp-movies-demo repo
• Examples using the Interactivity API at block-development-examples:
  • my-first-interactive-block
  • interactivity-api-countdown-3cd73e
  • interactivity-api-quiz-1835fa