wp-interactivity-api

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 + triage output (wp-project-triage).
• Which block/theme/plugin surfaces are affected (frontend, editor, both).
• Any constraints: WP version, whether modules are supported in the build.

Procedure

1) Detect existing usage + integration style

Search for:

• data-wp-interactive
• @wordpress/interactivity
• viewScriptModule

Decide:

• Is this a block providing interactivity via block.json view script module?
• Is this theme-level interactivity?
• Is this plugin-side “enhance existing markup” usage?

If you’re creating a new interactive block (not just debugging), prefer the official scaffold template:

• @wordpress/create-block-interactive-template (via @wordpress/create-block)

2) Identify the store(s)

Locate store definitions and confirm:

• state shape,
• actions (mutations),
• callbacks/event handlers used by data-wp-on--*.

3) Server-side rendering (best practice)

Pre-render HTML on the server before outputting to ensure:

• Correct initial state in the HTML before JavaScript loads (no layout shift).
• SEO benefits and faster perceived load time.
• Seamless hydration when the client-side JavaScript takes over.

Enable server directive processing

For components using block.json, add supports.interactivity:

{
  "supports": {
    "interactivity": true
  }
}

For themes/plugins without block.json, use wp_interactivity_process_directives() to process directives.

Initialize state/context in PHP

Use wp_interactivity_state() to define initial global state:

wp_interactivity_state( 'myPlugin', array(
  'items'    => array( 'Apple', 'Banana', 'Cherry' ),
  'hasItems' => true,
));