Goodbye jQuery? Mastering the WordPress Interactivity API
Introduction
For years, adding interactivity to WordPress blocks felt a bit like the Wild West. Do we queue jQuery? Do we load a heavy React bundle just for a simple toggle? Do we write vanilla JS and pray it doesn’t conflict with other plugins?
With the release of WordPress 6.5, the Interactivity API officially became the standard solution.
If you are a web agency, this is a major shift. The Interactivity API offers a standardized, lightweight way to add frontend interactivity to blocks without the performance cost of loading heavy external frameworks. It bridges the gap between the server (PHP) and the client (JavaScript) using a declarative, directive-based approach similar to Alpine.js or Vue.
In this guide, we’ll break down how to use it, provide real code examples, and weigh the pros and cons for your next client project.
What is the Interactivity API?
The Interactivity API is a standard system of directives that allows you to add behavior to your HTML. Instead of writing imperative JavaScript that manually selects DOM elements (e.g., document.querySelector('.my-button')), you add special attributes to your markup that “listen” to user actions and update the state automatically.
It is built on top of Preact, but you don’t need to be a React wizard to use it. It relies on two main concepts:
- Directives: HTML attributes (starting with
data-wp-) that connect elements to data. - The Store: A centralized place in your JavaScript where logic, state, and actions live.
How to Use It: A Practical Example
Let’s build a simple “Like Button” block. When clicked, it updates a counter and changes the text—all without a page reload.
Here is an SEO-optimized blog post tailored for a web development agency. It balances technical depth with readability, designed to rank for keywords like “WordPress Interactivity API tutorial,” “dynamic blocks,” and “frontend performance.”
Blog Post Draft
Title: Goodbye jQuery? Mastering the WordPress Interactivity API for Dynamic Blocks Target Audience: WordPress Developers, Technical Leads, Agency Clients Focus Keyword: WordPress Interactivity API
Introduction
For years, adding interactivity to WordPress blocks felt a bit like the Wild West. Do we queue jQuery? Do we load a heavy React bundle just for a simple toggle? Do we write vanilla JS and pray it doesn’t conflict with other plugins?
With the release of WordPress 6.5, the Interactivity API officially became the standard solution.
If you are a web agency, this is a major shift. The Interactivity API offers a standardized, lightweight way to add frontend interactivity to blocks without the performance cost of loading heavy external frameworks. It bridges the gap between the server (PHP) and the client (JavaScript) using a declarative, directive-based approach similar to Alpine.js or Vue.
In this guide, we’ll break down how to use it, provide real code examples, and weigh the pros and cons for your next client project.
What is the Interactivity API?
The Interactivity API is a standard system of directives that allows you to add behavior to your HTML. Instead of writing imperative JavaScript that manually selects DOM elements (e.g., document.querySelector('.my-button')), you add special attributes to your markup that “listen” to user actions and update the state automatically.
It is built on top of Preact, but you don’t need to be a React wizard to use it. It relies on two main concepts:
- Directives: HTML attributes (starting with
data-wp-) that connect elements to data. - The Store: A centralized place in your JavaScript where logic, state, and actions live.
How to Use It: A Practical Example
Let’s build a simple “Like Button” block. When clicked, it updates a counter and changes the text—all without a page reload.
Step 1: Update block.json
First, tell WordPress your block supports interactivity and link your view script.
{
"name": "agency/like-button",
"title": "Agency Like Button",
"supports": {
"interactivity": true
},
"viewScriptModule": "file:./view.js"
}Note: We use viewScriptModule because the API uses JavaScript Modules (ESM).
Step 2: The Logic (view.js)
Here we define our store. This holds the state (data) and actions (functions).
import { store, getContext } from '@wordpress/interactivity';
store( 'agency/like-button', {
state: {
get likesText() {
const context = getContext();
return `${context.likes} People liked this`;
}
},
actions: {
toggleLike: () => {
const context = getContext();
context.isLiked = !context.isLiked;
if (context.isLiked) {
context.likes++;
} else {
context.likes--;
}
}
},
callbacks: {
logClick: () => {
console.log("Button interaction detected");
}
}
} );Step 3: The Markup (render.php)
Now we bind our HTML to the store using directives.
<?php
// Initial state passed from the server
$context = array(
'likes' => 10,
'isLiked' => false
);
?>
<div
data-wp-interactive="agency/like-button"
<?php echo wp_interactivity_data_wp_context( $context ); ?>
>
<p data-wp-text="state.likesText"></p>
<button
data-wp-on--click="actions.toggleLike"
data-wp-bind--aria-pressed="context.isLiked"
data-wp-class--is-active="context.isLiked"
data-wp-watch="callbacks.logClick"
>
<span data-wp-text="context.isLiked ? 'Unlike' : 'Like'"></span>
</button>
</div>What’s happening here?
data-wp-interactive: Initializes the specific store namespace.data-wp-context: Provides local data (like props in React) that is specific to this specific instance of the block.data-wp-on--click: Listens for a click event and runs thetoggleLikeaction.data-wp-class--is-active: Automatically adds/removes the class.is-activebased on the state.
Pros and Cons of the Interactivity API
Should you rewrite all your agency’s blocks? Let’s look at the trade-offs.
✅ The Pros
- Blazing Fast Performance: The API is incredibly lightweight. It only loads the necessary JavaScript modules when the block is actually present on the page.
- Instant Feedback: Because the state is handled on the client, interactions happen instantly (no waiting for AJAX calls unless you specifically program them).
- Server-Side Rendering (SSR) Compatible: Unlike a full React app, the initial HTML is rendered by PHP. This is huge for SEO and Core Web Vitals (LCP) because the content is visible immediately before the JS even loads.
- Declarative Code: It separates logic from presentation. Your HTML tells you exactly what it does (
data-wp-on--click), making the code easier to maintain than spaghetti jQuery files. - Context Aware: You can have 10 different “Like” buttons on one page, and they will all track their own separate click counts automatically via
context.
❌ The Cons
- Learning Curve: Developers used to jQuery or vanilla JS need to learn the specific syntax of directives (
data-wp-*) and the Store structure. - Debugging Complexity: Since the logic is abstracted into the store, you can’t always just “inspect element” to see what event listener is attached. You need to rely on the API’s debugging tools.
- Not for Full Applications: It is designed for blocks. If you are building a complex Dashboard or a Single Page Application (SPA), React or Vue is still the better choice.
- Documentation Gaps: As a newer feature (WP 6.5+), the ecosystem of tutorials and StackOverflow answers is smaller compared to established methods.
Conclusion: When should you use it?
The Interactivity API is the future of interactive content in WordPress.
- Use it for: Toggles, lightboxes, “load more” buttons, live search, simple calculators, and shopping cart sidebars.
- Skip it for: Complex application dashboards or static blocks that require zero JavaScript.
For agencies, adopting this API means delivering websites that score higher on Google PageSpeed Insights while keeping the codebase standardized.