wp-interactivity-api

SKILL.md

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,
));

For local context, use wp_interactivity_data_wp_context():

<?php
$context = array( 'isOpen' => false );
?>
<div <?php echo wp_interactivity_data_wp_context( $context ); ?>>
  ...
</div>

Define derived state in PHP

When derived state affects initial HTML rendering, replicate the logic in PHP:

wp_interactivity_state( 'myPlugin', array(
  'items'    => array( 'Apple', 'Banana' ),
  'hasItems' => function() {
    $state = wp_interactivity_state();
    return count( $state['items'] ) > 0;
  }
));

This ensures directives like data-wp-bind--hidden="!state.hasItems" render correctly on first load.

For detailed examples and patterns, see references/server-side-rendering.md.

4) Implement or change directives safely

When touching markup directives:

keep directive usage minimal and scoped,

prefer stable data attributes that map clearly to store state,

ensure server-rendered markup + client hydration align.

WordPress 6.9 changes:

data-wp-ignore is deprecated and will be removed in future versions. It broke context inheritance and caused issues with client-side navigation. Avoid using it.

Unique directive IDs: Multiple directives of the same type can now exist on one element using the --- separator (e.g., data-wp-on--click---plugin-a="..." and data-wp-on--click---plugin-b="...").

New TypeScript types: AsyncAction<ReturnType> and TypeYield<T> help with async action typing.

For quick directive reminders, see references/directives-quickref.md.

5) Build/tooling alignment

Verify the repo supports the required module build path:

if it uses @wordpress/scripts, prefer its conventions.

if it uses custom bundling, confirm module output is supported.

6) Debug common failure modes

If “nothing happens” on interaction:

confirm the viewScriptModule is enqueued/loaded,

confirm the DOM element has data-wp-interactive,

confirm the store namespace matches the directive’s value,

confirm there are no JS errors before hydration.

See references/debugging.md.

Verification

wp-project-triage indicates signals.usesInteractivityApi: true after your change (if applicable).

Manual smoke test: directive triggers and state updates as expected.

If tests exist: add/extend Playwright E2E around the interaction path.

Failure modes / debugging

Directives present but inert:

view script not loading, wrong module entrypoint, or missing data-wp-interactive.

Hydration mismatch / flicker:

server markup differs from client expectations; simplify or align initial state.

derived state not defined in PHP: use wp_interactivity_state() with closures.

Initial content missing or wrong:

supports.interactivity not set in block.json (for blocks).

wp_interactivity_process_directives() not called (for themes/plugins).

state/context not initialized in PHP before render.

Layout shift on load:

derived state like state.hasItems missing on server, causing hidden attribute to be absent.

Performance regressions:

overly broad interactive roots; scope interactivity to smaller subtrees.

Client-side navigation issues (WordPress 6.9):

getServerState() and getServerContext() now reset between page transitions—ensure your code doesn't assume stale values persist.

Router regions now support attachTo for rendering overlays (modals, pop-ups) dynamically.

Escalation

If repo build constraints are unclear, ask: "Is this using @wordpress/scripts or a custom bundler (webpack/vite)?"

Consult:

references/server-side-rendering.md

references/directives-quickref.md

references/debugging.md