A Complete Guide to WordPress’s Interactivity API

Here is a Complete Guide to WordPress’s Interactivity API.

The Interactivity API is one of WordPress’s most exciting recent additions, bringing modern front-end interactivity to block-based themes — without the need for heavy JavaScript frameworks like React or Vue. If you’re developing custom blocks or enhancing user experiences with dynamic behavior, this API is your new best friend.

In this blog post, we’ll explore what it is, why it matters, and how to use it with real-world examples.

---

What is the WordPress Interactivity API?

The Interactivity API is a lightweight, declarative JavaScript API that allows you to build dynamic and reactive behavior into your block themes using simple data-wp-* HTML attributes and store-driven state management.

It was introduced as part of WordPress’s push to enhance frontend block interactivity while staying lean and accessible for theme developers.

---

Key Features

• 🔁 Reactive State Management — similar to Vue or Alpine.js
• 🏷️ Declarative HTML Attributes — use data-wp-* directives to bind data and events
• 🧠 Contextual State — scoped to specific parts of your page
• ⚡ No Framework Needed — doesn’t require React or Vue
• 🧩 Block Friendly — designed to integrate with Gutenberg block rendering

---

Core Concepts

1. store(): State + Actions

The store() function lets you define reactive state, actions, and callbacks.

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

store('myplugin/counter', {
  state: () => ({
    count: 0
  }),
  actions: {
    increment() {
      const context = getContext();
      context.count++;
    }
  }
});

---

2. HTML Directives

You bind state and events directly in your block markup using data-wp-* attributes.

<div data-wp-interactive="myplugin/counter">
  <p data-wp-bind="text: count"></p>
  <button data-wp-on--click="actions.increment">Add</button>
</div>

This example binds a <p> to the count state and increments it on button click.

---

3. getContext(): Accessing Scoped State

The getContext() function returns the state and actions for the current element scope.

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

const context = getContext();
context.count += 1;

---

4. Callbacks

Callbacks let you run JS code in response to DOM changes or lifecycle events.

callbacks: {
  setupKeyListener() {
    window.addEventListener('keydown', (event) => {
      if (event.key === 'Escape') {
        store('myplugin/modal').actions.close();
      }
    });
  }
}

---

Real-World Use Case: AJAX Product Grid

Let’s say you want to load products by category when users click on a category card. Here’s how the Interactivity API helps:

HTML

<div data-wp-interactive="myplugin/products">
  <div class="category" data-wp-on--click="actions.loadCategory" data-category-id="12">
    View Electronics
  </div>

  <div class="products-grid" data-wp-bind="innerHTML: productsHtml"></div>
</div>

JavaScript Store

store('myplugin/products', {
  state: () => ({
    productsHtml: '',
    loading: false
  }),
  actions: {
    async loadCategory(event) {
      const context = getContext();
      const catId = event.target.dataset.categoryId;

      context.loading = true;
      const response = await fetch(`/wp-json/myplugin/v1/products/${catId}`);
      const data = await response.json();

      context.productsHtml = data.products.map(p =>
        `<div class="product">${p.name}</div>`
      ).join('');

      context.loading = false;
    }
  }
});

---

When Should You Use It?

The Interactivity API is perfect for:

• Product filters and grids
• Modals, toggles, and accordions
• Dynamic form interactions
• Search/autocomplete widgets
• Cart updates and WooCommerce customizations

---

Advantages Over Alternatives

Feature	Interactivity API	React	Alpine.js
Lightweight	✅ Yes	❌ No	✅ Yes
WordPress-native	✅ Yes	✅ Yes	❌ No
Declarative HTML	✅ Yes	❌ No	✅ Yes
Ideal for Block Themes	✅ Yes	✅ Yes (with effort)	❌ Not native

---

Limitations & Gotchas

• Still evolving — not all features are fully documented.
• Requires modern JavaScript understanding (ES6+).
• Complex logic may still benefit from React/Vue.

---

Further Resources

• Official Developer Docs
• Gutenberg GitHub
• Interactivity API Examples

---

Final Thoughts

The Interactivity API makes WordPress block development more powerful, elegant, and modern — especially for those who want reactive front-end behavior without committing to a full frontend framework.

If you’re building for WordPress in 2024 and beyond, this API is worth learning. It’s fast, flexible, and fits naturally into the Gutenberg/block theme ecosystem.