wp-interactivity-api

Use when building or debugging WordPress Interactivity API features: data-wp-* directives, @wordpress/interactivity store/state/actions, block viewScriptModule integration, performance, hydration, and directive behavior.

⭐3stars🔀0forks📁View on GitHub🕐Updated Jan 2, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides expert guidance for building and debugging WordPress Interactivity API features. It streamlines the development of interactive blocks by offering precise implementations of data-wp-* directives, state management via @wordpress/interactivity, and optimized viewScriptModule integration to ensure high-performance frontend experiences.

Use Cases

  • Scaffolding interactive blocks: Quickly generate block.json, view.js, and render.php files using the latest WordPress Interactivity API standards and templates.
  • State Management Implementation: Setting up global or local stores using @wordpress/interactivity to handle complex UI interactions, reactive data binding, and side effects.
  • Debugging Hydration & Execution: Identifying and resolving 'directives don't fire' errors, server-client markup mismatches, or script loading issues in the browser.
  • Performance Optimization: Implementing best practices for scoping interactivity to specific subtrees and managing asynchronous actions to improve Core Web Vitals.
  • Legacy Migration: Updating older WordPress blocks to use the modern Interactivity API and module-based view scripts introduced in WordPress 6.9+.
namewp-interactivity-api
description"Use when building or debugging WordPress Interactivity API features: data-wp-* directives, @wordpress/interactivity store/state/actions, block viewScriptModule integration, performance, hydration, and directive behavior."
compatibility"Targets WordPress 6.9+ (PHP 8.0+). Requires @wordpress/scripts for building."

WP Interactivity API

When to use

Use this skill when the user mentions:

  • Interactivity API, @wordpress/interactivity
  • data-wp-interactive, data-wp-on--*, data-wp-bind--*, data-wp-context
  • Block viewScriptModule / module-based view scripts
  • Hydration issues or "directives don't fire"

Inputs required

  • Repo root + project type (plugin, theme, block)
  • Which surfaces are affected (frontend, editor, both)
  • WordPress version constraints

Procedure

1) Set up interactivity in a block

block.json:

{
  "name": "my-plugin/interactive-block",
  "title": "Interactive Block",
  "viewScriptModule": "file:./view.js",
  "supports": {
    "interactivity": true
  }
}

view.js (ES module):

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

store('my-plugin', {
  state: {
    get isOpen() {
      return getContext().isOpen;
    }
  },
  actions: {
    toggle() {
      const context = getContext();
      context.isOpen = !context.isOpen;
    }
  }
});

2) Core directives reference

Directive Purpose Example
data-wp-interactive Activate interactivity on element data-wp-interactive="my-plugin"
data-wp-context Provide local state data-wp-context='{"isOpen": false}'
data-wp-bind--attr Bind attribute to state data-wp-bind--aria-expanded="state.isOpen"
data-wp-on--event Handle events data-wp-on--click="actions.toggle"
data-wp-class--name Toggle CSS class data-wp-class--is-open="state.isOpen"
data-wp-text Set text content data-wp-text="state.count"
data-wp-watch Run side effects data-wp-watch="callbacks.logChanges"

3) PHP render with directives

<?php
$context = array( 'isOpen' => false );
?>
<div
  <?php echo get_block_wrapper_attributes(); ?>
  data-wp-interactive="my-plugin"
  <?php echo wp_interactivity_data_wp_context( $context ); ?>
>
  <button data-wp-on--click="actions.toggle">
    Toggle
  </button>
  <div data-wp-bind--hidden="!state.isOpen">
    Content here
  </div>
</div>

4) WordPress 6.9 changes

Deprecated:

  • data-wp-ignore is deprecated - avoid using it

New features:

  • Unique directive IDs with --- separator:
    data-wp-on--click---plugin-a="actions.handleA"
    data-wp-on--click---plugin-b="actions.handleB"
    
  • New TypeScript types: AsyncAction<ReturnType>, TypeYield<T>
  • getServerState() and getServerContext() reset between page transitions

5) Create interactive block from scratch

npx @wordpress/create-block@latest my-interactive-block --template @wordpress/create-block-interactive-template

This scaffolds:

  • block.json with viewScriptModule
  • view.js with store setup
  • render.php with directives

Verification

  • Manual smoke test: directive triggers and state updates as expected
  • View script loads in browser Network tab
  • No JS console errors before hydration
  • If tests exist: add/extend Playwright E2E

Failure modes / debugging

Directives not firing:

  • View script not loading - check viewScriptModule path
  • Missing data-wp-interactive on parent element
  • Store namespace mismatch
  • JS errors before hydration

Hydration mismatch / flicker:

  • Server markup differs from client expectations
  • Simplify or align initial state

Performance issues:

  • Overly broad interactive roots
  • Scope interactivity to smaller subtrees

Debug checklist:

# Check view script is registered
wp eval 'print_r(wp_scripts()->registered);' | grep "view"

# Check for interactivity usage
grep -r "data-wp-interactive" .
grep -r "@wordpress/interactivity" .

Escalation

If build constraints are unclear, ask:

"Is this using @wordpress/scripts or a custom bundler (webpack/vite)?"

Consult: