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:

• Interactivity API Reference

• Interactivity API Docs