(In response to Mark and Keith about the Interactivity API, following a discussion they had on their WP Café video podcast. )


  • The WordPress Interactivity API provides a way of adding Javascript interaction to content blocks which are output on the frontend of the website.
  • If you don’t know React then it’s a good way to get started on interactivity without having to write everything yourself. If you do know React, or how to write plain JavaScript to add click handlers and the like, then your own code can be more efficient, smaller and more maintainable.
  • If you base your code on the Interactivity API you might have to wait a long time for core bugs to be fixed or for features to be added to the API.
  • This API is exclusively part of WordPress. (See footnote 1.)
  • If you want to learn how to code interactive elements for sites which don’t use WordPress, learn how to do that without using this API. That way, you can always apply the same code principles, irrespective of the website or system for which it is intended.
  • Some information in this article was added after its initial publication on 1st March.

The WordPress Interactivity API (mainly) provides a “framework” which allows developers to use pre-defined methods to add JavaScript interaction to blocks. Although the main functionality for developers is coming im WordPress 6.5, a small part of it was introduced with WordPress 6.4 when the “expand on click” feature was introduced to the core image block. 2

If you’re a developer, inspect the HTML of the following image block. You’ll see inline configuration for Javascript functionality; values and references to click handlers. These complex rules are applied to the block so that the Interactivity API can interact with the content. (In this case, zooming the image to a larger size when you click on it.)

The JavaScript file which is loaded for the core image block when this “expand” feature is activated is over 5kb, which is way heavier than a self-coded script for the same functionality. Additionally, the base script for the API, which contains the functionality which is shared across all blocks, is over 30kb but is only loaded when there is a block on the page which will need it. This is good for performance.

The principle behind the API—a “standardised” way of programming interactive frontend functionality like button clicks, modals and so on—is a good idea if there is a team which is working on this kind of stuff, so that everyone is building things in the same way. There are easier ways of building this kind of interactive interface: plain Javascript or React being two which are obvious. Learning frameworks like this one require learning two things: the initial code (or principle) of Javascript, and the framework.

Discussions on Twitter/X since I originally published this blog post clarified that the basis of the new API is, in fact, Preact: a trimmed-down version of React which I’ve been using over the past few years. It’s not clear yet how the approaches to React projects and projects with the new API work together, or whether this is possible or necessary. I’ll definitely be keeping an eye on the API as soon as more code examples come online.

The speed of development is a key argument. Most people want to achieve things more quickly. But if you use a framework—the “Interactivity API” as this one is called, although it’s not an API—you have to make a decision about the trade-offs in terms of performance and complexity. You also have to bear in mind that not only do you have to know and understand the principles behind coding for interactive elements, but also how to use the Interactivity API.

The documentation on WordPress.org is, thankfully, comparatively extensive, but it certainly needs a moderately good understanding of JavaScript and state management. (If you’re already using React, the idea should be familiar to you. However, if you already use React, then you may well not need this API.)

In an ideal scenario, you would choose to learn the base language, JavaScript, and then use a framework where it benefits you. That’s why I build web app functionality with React, accepting the minimal technical overhead for less time-consuming creation of interactive views. If I hadn’t already learned React, the new API might make more sense, but only if I never planned to create outside the WordPress ecosystem. However, I also build interactive solutions without WordPress, ensuring that my skills and projects aren’t limited by a dependency on WordPress-specific APIs.

If you want to learn portable skills—Javascript which works independently of WordPress—then you’re better off building and implementing code which isn’t bound to principles set out by WordPress contributors. Particularly because the possibilities are more limited than much more established solutions, and also because you’re always dependent on the core developers behind WordPress fixing bugs they introduce or adding functionality you need. Developers have faced issues with WordPress’s CSS decisions since the Block Editor’s introduction, particularly as some errors have remained unresolved for years.

If you’re competent in writing JavaScript, then you shouldn’t be using the Interactivity API unless you want to submit your work to an official open-source repository, or if you or your team doesn’t have an established way of building interactive interfaces.

The benefits of using the Interactivity API include reliance on a base code which a team containing experts has provided, which is a strong reason to use it. However, as many WordPress specialist developers have found over the past five or six years, relying on the complicated basis of code which WordPress core developers provide means that you’re fully dependent on the quality of their work and on the speed of them fixing or amending work they’ve delivered.


  1. Since initially posting this article, core developer Jon Surrell has reached out on X and clarified that the scripts which power the frontend functionality of the Interactivity API are publicly available as an NPM module. ↩︎
  2. The linked explanation is on the hosted version of WordPress, but applies equally to the version which can be installed on your own server. ↩︎

Leave a Reply

Your email address will not be published. Required fields are marked *

For security, use of Google’s reCAPTCHA service is required which is subject to the Google Privacy Policy and Terms of Use.

This site uses Akismet to reduce spam. Learn how your comment data is processed.