Introduction to the WordPress Interactivity API: A Modern Approach to Block Interactivity

The WordPress Interactivity API (IAPI) represents a fundamental shift in how developers add client-side interactivity to WordPress blocks. Introduced in WordPress 6.5 and standardized in 6.6, it provides a declarative, reactive system that works harmoniously with WordPress’s server-side rendering architecture.

If you’ve worked with Alpine.js, Vue.js, or Svelte, many concepts will feel familiar. The IAPI brings similar reactive patterns to WordPress while maintaining compatibility with block themes, full-page caching, and progressive enhancement principles.

The Problem It Solves

Before the Interactivity API, developers faced several challenges when building interactive blocks:

Inconsistent Approaches: Some developers used jQuery, others common frameworks like React or Vue, others vanilla JavaScript, and some implemented React hydration patterns. This fragmentation made blocks harder to maintain and created potential conflicts.

Caching Conflicts: Traditional JavaScript approaches often fought against WordPress’s caching systems. Full-page caching and dynamic interactivity seemed mutually exclusive.

Hydration Complexity: Using React for both the editor and frontend meant implementing complex hydration strategies, dealing with mismatches between server-rendered HTML and client-side expectations.

Performance Overhead: Loading full React or Vue libraries just for simple interactions added unnecessary weight to the frontend.

The Interactivity API solves these problems by providing a lightweight, standardized system specifically designed for WordPress’s architecture.

Core Architecture

The IAPI consists of three interconnected layers that work together seamlessly:

Server-Side Rendering (PHP)

Your block’s HTML is generated server-side using PHP, just like traditional WordPress development. This ensures excellent SEO, fast initial page loads, and accessibility. The key difference is that you add special data-wp-* attributes to your HTML that serve as hooks for client-side interactivity.

This server-first approach means your content is immediately visible to users and search engines, regardless of JavaScript availability. The HTML contains all the necessary content and structure, with attributes that describe how it should behave once JavaScript loads.

Client-Side Store (JavaScript)

The store is where your block’s logic lives. It’s a JavaScript object that defines reactive state, actions (functions that respond to user interactions), and callbacks (side effects that run when state changes). The store is defined once but can power multiple instances of your block on the same page.

Think of the store as your block’s “brain”—it centralizes all the behavioral logic in one predictable location. This makes debugging easier, testing simpler, and code more maintainable.

Directives System

Directives are special HTML attributes that connect your DOM elements to your store. They declaratively define how elements should behave: what state they should display, what actions they should trigger, when they should appear or hide. The IAPI watches these directives and automatically updates the DOM when the underlying state changes.

This declarative approach means you describe what should happen, not how to make it happen. The API handles the implementation details—DOM manipulation, event binding, and efficiency optimizations—leaving you to focus on your block’s logic.

Understanding the Store

Every interactive block needs a store, defined using the store() function from @wordpress/interactivity. The store namespace should be unique and typically follows the pattern pluginName/blockName.

State: Reactive Data

State contains the reactive data that drives your interface. When state values change, any DOM elements bound to those values automatically update. State should contain simple, serializable values: strings, numbers, booleans, arrays, and plain objects.

It’s important to understand that the state defined in the store is global—shared across all instances of your block on a page. This is useful for data that should be synchronized across instances, like theme settings or global UI state. However, for most cases where each block instance needs its data, you’ll use context instead.

Actions: Event Handlers

Actions are functions that execute in response to user interactions. They’re your event handlers, but with a crucial difference from traditional JavaScript: they work within the reactive system, automatically triggering UI updates when they modify state.

Actions can be synchronous or asynchronous. For asynchronous operations like API calls, the IAPI uses generator functions (functions prefixed with *). This provides a clean syntax for handling async operations without callback hell or complex promise chains.

When an action modifies state, the IAPI automatically determines which parts of the DOM need to update and efficiently applies those changes. You never manually manipulate the DOM—you just update state and let the system handle the rest.

Callbacks: Side Effects

Callbacks are functions that run automatically when specific state changes occur. They’re useful for operations that shouldn’t directly modify state but need to react to changes: logging, analytics, triggering external APIs, or updating browser storage.

Think of callbacks as “watchers” that observe your data. They don’t return values or modify state directly—they perform side effects in response to state changes. This separation of concerns keeps your code clean and predictable.

Context: Instance-Specific State

While store state is global, context provides instance-specific state. This is one of the most important concepts in the IAPI and often misunderstood by newcomers.

Context is initialized server-side in your PHP render function and attached to specific DOM elements via the data-wp-context attribute. Each block instance on a page has its own isolated context, preventing conflicts between multiple instances.

Context Hierarchy

Context is hierarchical and inherits down the DOM tree. A child element inherits all context values from its parent and can override specific values for itself and its descendants. This creates a natural scoping system that mirrors your HTML structure.

For example, if you have a parent element with data-wp-context='{"theme": "dark"}' and a child with data-wp-context='{"isOpen": false}', the child element has access to both theme and isOpen. If the child also defined theme, it would override the parent’s value for itself and its descendants.

This hierarchical system is particularly powerful for nested interactive components or list items where each item needs similar functionality but different data.

Accessing Context in Actions

Inside actions and callbacks, you access the current context using getContext(). This function returns the context object for the element that triggered the action, including all inherited values.

The context you receive is reactive—when you modify its values, any DOM elements bound to those values automatically update. This is the core of the IAPI’s reactivity system.

Derived State: Computed Values

Derived state (also called computed state) represents values calculated from other state values. Instead of storing redundant data that must be manually kept in sync, you define getters that compute values on demand.

The beauty of derived state is that it’s reactive. When the underlying values change, any derived values automatically recalculate, and any DOM elements bound to those derived values automatically update. You never worry about keeping computed values in sync—the system handles it for you.

Derived state keeps your data model DRY (Don’t Repeat Yourself) and prevents entire categories of bugs related to data synchronization. If you find yourself updating multiple state values whenever one changes, you probably need derived state instead.

You can define derived state both in your store (for global computed values) and in your context (for instance-specific computed values). The syntax is the same: use getters that access other values through getContext().

Accessing State in Actions

In the Interactivity API, there are three ways to access data within actions, and understanding the distinction is crucial:

1. Context via getContext()

Context is instance-specific data and is accessed using getContext(). This is what you’ll use most of the time:

javascript

actions: {
toggle() {
const context = getContext();
context.isOpen = !context.isOpen;
}
}

Context represents the data for the specific block instance that triggered the action. Each block on the page has its own isolated context.

2. State via getContext() with State Properties

Here’s the key insight: state properties are also accessible through getContext(). When you define properties in your store’s state object, they become available on the context:

javascript

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

store('myPlugin/cart', {
state: {
taxRate: 0.1,
shippingCost: 5.99,
get total() {
const context = getContext();
return context.subtotal + (context.subtotal * context.taxRate);
}
},
actions: {
addToCart() {
const context = getContext();

// Access instance context (from data-wp-context)
context.cartItems.push(item);

// Access global state (from store definition)
const tax = context.subtotal * context.taxRate;
const shipping = context.shippingCost;

// Access derived state (also via context)
context.cartTotal = context.total;
}
}
});

The context object merges both the instance-specific context (from data-wp-context in your HTML) and the global state (from your store definition). This unified access pattern is intentional—it simplifies the mental model and API surface.

3. Direct State Access via state (Advanced)

If you need to access the raw state object directly (without context), you can use the state property of the store, but this is rarely necessary and breaks the context hierarchy:

javascript

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

const { state } = store('myPlugin/cart', {
state: {
taxRate: 0.1
},
actions: {
calculate() {
// This bypasses context and accesses global state directly
const tax = state.taxRate;

// But you lose access to instance context this way
// So this pattern is discouraged
}
}
});

This approach is generally not recommended because it breaks the context system’s flexibility and makes your code less maintainable.

The Correct Pattern

For your addToCart example, the correct approach is:

javascript

actions: {
addToCart() {
const context = getContext();

// Modify instance context
context.cartItems.push(item);

// Access derived state through context
context.cartTotal = context.total;

// Or if total is not derived, calculate using state values
const subtotal = context.cartItems.reduce((sum, item) =>
sum + (item.price * item.quantity), 0
);
context.cartTotal = subtotal + (subtotal * context.taxRate);
}
}

The key principle: Always use getContext() within actions and callbacks. It provides unified access to both instance context and global state, maintaining the proper hierarchy and scoping.

The Directives System

Directives are the bridge between your HTML and your store. They’re special attributes prefixed with data-wp- that declaratively define behavior. The IAPI recognizes these attributes and automatically sets up the necessary reactivity and event handling.

Namespace and Context Directives

data-wp-interactive establishes the interactive scope and identifies which store powers this section of the DOM. It must be present on the root element of any interactive block and match your store’s namespace.

data-wp-context initializes the context for a block instance or section. The value must be valid JSON, typically generated server-side using wp_json_encode(). This directive creates a new context scope, inheriting from any parent context.

Data Binding Directives

• data-wp-bind--[attribute] creates reactive bindings to any HTML attribute. The [attribute] portion can be any valid HTML attribute: value, href, src, disabled, aria-expanded, custom data attributes, or any other attribute.

When the bound state value changes, the attribute automatically updates. For form inputs, this can create two-way binding when combined with event handlers that update state on user input.

data-wp-text sets the text content of an element, automatically escaping any HTML to prevent XSS attacks. This is the safe, recommended way to display user-provided text.

data-wp-html sets the HTML content of an element. Use this only with trusted, sanitized data, such as content from WordPress’s REST API that has already been sanitized server-side. Never use this with unsanitized user input.

Conditional Rendering Directives

data-wp-class--[classname] conditionally adds or removes CSS classes based on state. The expression after the double dash becomes the class name when the condition is truthy. You can use multiple class directives on a single element to manage different visual states independently.

data-wp-style--[property] sets inline CSS properties dynamically. While CSS classes are usually preferable for maintainability, this directive is invaluable for truly dynamic styling like progress bars, color pickers, or draggable elements.

data-wp-show conditionally displays or hides elements using display: none. The element remains in the DOM but becomes invisible when the condition is falsy. This is simpler than conditional rendering but keeps the element in memory.

Event Handling Directives

• data-wp-on--[event] attaches event listeners that trigger actions in your store. The [event] portion matches standard DOM events: click, input, change, submit, focus, blur, or any other DOM event.

When the event fires, the specified action executes with access to the current context. The action can modify state, trigger other actions, or perform any JavaScript operation.

Event Handling Directives

• data-wp-on--[event] attaches event listeners that trigger actions in your store. The [event] portion matches standard DOM events: click, input, change, submit, focus, blur, or any other DOM event.

When the event fires, the specified action executes with access to the current context. The action can modify state, trigger other actions, or perform any JavaScript operation. This directive works for both synchronous actions and asynchronous actions (generator functions with *).

Accessing Event Objects: When you need to access event properties or call methods like preventDefault(), use withSyncEvent():

import  { store, getContext, withSyncEvent }  from  '@wordpress/interactivity';
...
actions: {
handleSubmit() {
withSyncEvent((event) => {
event.preventDefault();
});

const context = getContext();
context.submitted = true;
}
}

getElement() provides direct access to the DOM element that triggered the action:

import  { store, getContext, getElement }  from  '@wordpress/interactivity';
...
actions: {
handleInput() {
const context = getContext();
const element = getElement();
context.value = element.value;
}
}

List Rendering Directives

• data-wp-each--[item] iterates over arrays in your context, rendering a template for each item. The [item] becomes the variable name accessible within each iteration. You must wrap the template content in a <template> tag.

Each iteration creates a new context scope with the current item, making it easy to bind properties or trigger item-specific actions. The IAPI efficiently handles array updates, only manipulating the DOM nodes that changed rather than re-rendering the entire list.

• data-wp-each-key provides stable identifiers for list items, crucial for performance when lists change. The API uses these keys to track which items were added, removed, or reordered, allowing minimal DOM manipulation.

How It All Works Together

When a page loads, the IAPI scans the DOM for elements with data-wp-interactive attributes. For each interactive block it finds, it:

1. Loads the corresponding store definition
2. Initializes the context from data-wp-context attributes
3. Processes all directives, setting up reactive bindings
4. Attaches event listeners for data-wp-on directives
5. Performs the initial render based on current state

From that point forward, the system is purely reactive:

• User interactions trigger actions
• Actions modify state or context
• The IAPI detects these changes
• Only the affected DOM elements update
• Callbacks run for any side effects

This reactive cycle continues throughout the user’s session, providing smooth, efficient interactivity without manual DOM manipulation.

Progressive Enhancement in Practice

The IAPI embraces progressive enhancement as a core principle. Your PHP render function generates complete, semantic HTML that works without JavaScript. When JavaScript loads, the experience enhances with smooth interactivity.

This approach has multiple benefits:

SEO: Search engines see complete content immediately, without waiting for JavaScript execution or client-side rendering.

Performance: Initial page loads are fast because content is immediately visible. JavaScript enhancement happens progressively in the background.

Accessibility: Screen readers and other assistive technologies can access content even if JavaScript fails or is disabled.

Resilience: If JavaScript errors occur or loading fails, users still get functional content rather than a blank page or broken interface.

Why the IAPI Excels

Native WordPress Integration

The Interactivity API is built by the WordPress core team specifically for WordPress. It understands block themes, the Site Editor, WordPress’s caching architecture, and the REST API. You’re not fighting against WordPress—you’re working with its strengths.

Performance by Default

The API implements sophisticated optimizations automatically. It uses efficient DOM diffing, batches updates, and only hydrates interactive elements. Static content remains static, reducing JavaScript overhead.

Maintainable Code

The declarative approach and centralized store make code easier to understand and maintain. You can see what an element does by reading its attributes. Debugging is simpler because state lives in predictable locations.

Future-Proof

WordPress is migrating core blocks to the IAPI and building new features around it. By adopting this API, you align with WordPress’s long-term vision and ensure your blocks remain compatible with future WordPress versions.

Reduced Complexity

You don’t manage React components, hydration strategies, or complex state libraries. The IAPI provides exactly what you need for block interactivity without the overhead of full frontend frameworks.

When to Use the Interactivity API

The IAPI is ideal for blocks that need client-side interactivity: toggles, tabs, accordions, modals, live search, filtering, form validation, API integration, or any dynamic user interface.

It’s particularly powerful when you need multiple instances of a block on the same page, each with independent state. The context system handles this naturally, eliminating the complexity of managing multiple component instances.

For blocks that are purely static or only need server-side rendering, the IAPI isn’t necessary. Use it when you need reactivity, user interactions, or dynamic updates without page reloads.

Conclusion

The WordPress Interactivity API represents a mature, thoughtful approach to adding interactivity to WordPress blocks. By understanding the store paradigm, the context system, derived state, and the directives system, you can build sophisticated interactive experiences that feel native to WordPress.

The API’s strength lies in its balance: powerful enough for complex applications, simple enough for basic interactions, and designed specifically for WordPress’s architecture. It’s not trying to be React or Vue—it’s a purpose-built solution for the specific challenges of WordPress block development.

Start exploring with simple blocks to grasp the fundamentals, then gradually tackle more complex patterns. The declarative nature and reactive system make development more intuitive once you internalize the core concepts. The IAPI isn’t just another framework—it’s the future of interactive blocks in WordPress.

And we have only scratched the surface here…

Taking Your Skills Further

The WordPress Interactivity API opens up exciting possibilities for building modern, reactive blocks that feel native to WordPress. While this introduction covers the fundamentals, there’s much more to explore: advanced patterns, performance optimization, testing strategies, and real-world implementation techniques.

Free Interactivity API Guide

I’ve created a comprehensive, free guide that goes deeper into the Interactivity API with practical examples, common patterns, and solutions to frequently encountered challenges:

• Build interactive blocks without external frameworks—Master the native Interactivity API to create dynamic, app-like experiences directly in WordPress with zero React or Vue overhead.
• Learn from 9 plugin code examples—Every concept in the guide includes battle-tested code you can copy and implement immediately in your projects.
• Eliminate hydration errors and performance issues—Discover the exact patterns professionals use to prevent common bugs and keep sites blazingly fast.

Download the free Interactivity API Guide →

Master WordPress Block Development

If you’re serious about becoming proficient in WordPress block development, I’ve written “WordPress Editor and Blocks”→—a complete resource covering everything from basic blocks to advanced techniques, including the Interactivity API, block themes, and the Site Editor.

Whether you’re building your first interactive block or architecting complex block-based applications, understanding the Interactivity API is essential for modern WordPress development. Start with the fundamentals in this guide, explore the patterns in the free resource, and master the complete ecosystem with the book.

The future present of WordPress is blocks, and the future of blocks is interactive. Now you have the foundation to build on it.