Wp Interactivity API

What Is This?

Overview

The WordPress Interactivity API is a standardized framework introduced in WordPress 6.1 and stabilized in WordPress 6.5 for building interactive, reactive block-based user interfaces on the front end. It provides a declarative programming model using HTML directives, a reactive store for managing state and actions, and a lightweight JavaScript runtime that handles DOM updates without requiring a full JavaScript framework like React or Vue on the client side.

The API centers on two main concepts: directives and the store. Directives are special HTML attributes prefixed with data-wp-* that bind DOM elements to reactive state. The store, powered by the @wordpress/interactivity package, holds the global state, derived values, and actions that directives reference. When state changes, the runtime automatically updates only the affected DOM nodes, making interactions fast and efficient.

This skill targets WordPress 6.9 and later, running on PHP 7.2.24 or higher. It is designed for filesystem-based development environments with bash and Node.js available, and some advanced workflows benefit from WP-CLI for server-side operations.

Who Should Use This

• Block developers building interactive Gutenberg blocks that require front-end reactivity without loading a full JavaScript framework.
• Theme developers who need to add dynamic behavior to block-based themes using a supported, performance-conscious approach.
• Plugin authors integrating interactive UI components such as filters, tabs, accordions, or live search into WordPress-powered sites.
• Performance engineers optimizing Time to Interactive metrics by replacing heavy JavaScript solutions with the lightweight Interactivity API runtime.

Why Use It?

Problems It Solves

• Framework fragmentation: Before this API, developers used inconsistent approaches including jQuery, Alpine.js, or custom React bundles, leading to conflicts and maintenance overhead.
• Hydration complexity: Server-rendered HTML often lost interactivity after page load. The API provides a structured hydration mechanism that reconnects server state to client-side reactivity automatically.
• Performance overhead: Loading full JavaScript frameworks for simple interactions wastes bandwidth. The Interactivity API runtime is small and shared across all blocks using it.
• Lack of standardization: There was no official WordPress pattern for reactive state management in blocks, making code difficult to maintain across teams and projects.

Core Highlights

• Declarative data-wp-* directives for binding, events, classes, styles, and visibility
• Reactive store with state, derived values, and actions via @wordpress/interactivity
• Built-in server-side state initialization using wp_interactivity_state()
• Automatic partial DOM updates without full page reloads
• Support for viewScriptModule in block.json for module-based script loading
• Namespace isolation to prevent store collisions between blocks and plugins
• Compatible with WordPress server-side rendering and render.php block templates
• No external dependencies required beyond the WordPress core package

How to Use It?

Basic Usage

Register your block with a viewScriptModule in block.json:

{
  "viewScriptModule": "file:./view.js"
}

Initialize server-side state in render.php:

<?php
wp_interactivity_state( 'my-plugin/counter', array(
  'count' => 0,
) );
?>
<div
  data-wp-interactive="my-plugin/counter"
  data-wp-context='{"count": 0}'
>
  <p data-wp-text="state.count"></p>
  <button data-wp-on--click="actions.increment">Increment</button>
</div>

Define the store in view.js:

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

store( 'my-plugin/counter', {
  actions: {
    increment() {
      const context = getContext();
      context.count++;
    },
  },
} );

Specific Scenarios

Toggling visibility: Use data-wp-bind--hidden or data-wp-class--is-open to show or hide elements based on store state without writing manual DOM manipulation code.

Async data fetching: Define an async action in the store, call a REST API endpoint, update state with the response, and let directives reflect the new data automatically.

Real-World Examples

• A product filter block that updates visible items reactively as users select categories, without page reloads.
• An accordion block where each panel tracks its open state in context, allowing multiple independent instances on the same page.
• A live character counter for a comment form that reads input length and updates a display element through data-wp-text.

When to Use It?

Use Cases

• Building interactive navigation menus with open and close states
• Creating real-time search or filter interfaces within block themes
• Adding tabbed content interfaces to custom blocks
• Implementing lazy-loaded content sections triggered by user scroll or click
• Building shopping cart indicators or notification counters that update without page refresh
• Adding form validation feedback that responds to user input in real time
• Replacing legacy jQuery-based interactions in modernized block-based themes

Important Notes

Requirements

• WordPress 6.9 or later for full directive and store feature support
• PHP 7.2.24 or higher on the server
• Node.js and npm available for building assets with @wordpress/scripts
• WP-CLI recommended for scaffolding blocks and running server-side debugging commands

FAQ

Q: How can I use the Wp Interactivity API skill to debug data-wp-* directives in WordPress blocks?

The Wp Interactivity API skill on Happycapy helps you analyze and troubleshoot data-wp-* directives within your WordPress blocks, making it easier to identify issues and optimize interactivity features.

Q: Does this skill support working with the @wordpress/interactivity store and actions?

Yes, this Skills tool is designed to assist with the @wordpress/interactivity store, state, and actions, providing guidance for AI agent workflows that interact with WordPress interactivity features.

Q: Can Happycapy AI agents use this skill to automate testing of WordPress block interactivity?

Happycapy AI agents can leverage this skill to automate and streamline the testing process for WordPress block interactivity, ensuring your features work as intended.

Q: What are the main benefits of using the Wp Interactivity API skill for WordPress developers?

This Skills integration allows developers to quickly build, debug, and refine interactive WordPress blocks, saving time and reducing errors when working with interactivity APIs.

Q: Is it possible to integrate this skill with other Happycapy Skills for a more comprehensive WordPress development workflow?

Yes, you can combine the Wp Interactivity API skill with other Happycapy Skills to create a powerful AI agent-driven workflow for end-to-end WordPress development and debugging.