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

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

Debugging checklist

1. Confirm the interactive root exists in the rendered HTML (data-wp-interactive). 2. Confirm the view script module is loaded (network + source maps). 3. Confirm store namespace matches what markup expects. 4. Check console for errors before any interaction. 5. Reduce scope:

• temporarily remove directives to isolate which directive/store path breaks.

6. If hydration mismatch occurs:

• ensure initial state/context matches server markup.

WordPress 6.9 specific issues

State not persisting across navigation:

• getServerState() and getServerContext() now reset between client-side page transitions.
• If you relied on stale values persisting, refactor to use the store's reactive state instead.

Multiple plugins conflicting on same element:

• Use unique directive IDs with the --- separator to avoid attribute collisions.
• Example: data-wp-on--click---my-plugin="actions.handle"

`data-wp-ignore` not working:

• This directive is deprecated in 6.9 and will be removed. It caused context inheritance and navigation bugs.
• Find an alternative approach (conditional rendering, separate interactive regions).

Router regions / overlays not rendering:

• WordPress 6.9 adds attachTo property for router regions to render overlays anywhere on the page.
• Ensure nested router regions are properly structured.

Directives quick reference (high level)

Common directives to recognize in markup:

• data-wp-interactive: declares an interactive region (and often a store namespace).
• data-wp-context: provides server-rendered context/state.
• data-wp-on--event: attaches event handlers (e.g. click, submit).
• data-wp-on-async--event: async event handlers (preferred for most actions).
• data-wp-bind--attr: binds DOM attributes to state.
• data-wp-class--name: toggles CSS classes based on state.

Use these as search anchors when triaging bugs.

Unique directive IDs (WordPress 6.9+)

HTML doesn't allow duplicate attributes. To attach multiple handlers of the same type from different plugins, use the --- separator:

<button
  data-wp-on--click---plugin-a="actions.handleA"
  data-wp-on--click---plugin-b="actions.handleB"
>

Both handlers will fire. The ID after --- must be unique per element.

Deprecated directive

• `data-wp-ignore`: Deprecated in WordPress 6.9. It was intended to prevent hydration of a region but broke context inheritance and client-side navigation. Will be removed in future versions. Avoid using it.

Server-Side Rendering for Interactivity API

• Faster initial render: HTML arrives ready with correct values.
• No layout shift: Hidden elements stay hidden from the first paint.
• SEO benefits: Search engines see fully rendered content.
• Graceful degradation: Content displays correctly even before JavaScript loads.

Setup Requirements

1. Enable Server Directive Processing

For components using `block.json`:

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

For themes/plugins without `block.json`:

Use wp_interactivity_process_directives() to manually process directives (see "Themes and Plugins without block.json" section below).

2. Initialize Global State with wp_interactivity_state()

Define initial state values in PHP before rendering:

wp_interactivity_state( 'myPlugin', array(
  'fruits'    => array( 'Apple', 'Banana', 'Cherry' ),
  'isLoading' => false,
  'count'     => 3,
));

The state is serialized and available to client JavaScript automatically.

3. Initialize Local Context with wp_interactivity_data_wp_context()

For element-scoped context:

<?php
$context = array(
  'isOpen'   => false,
  'itemId'   => 42,
  'itemName' => 'Example',
);
?>
<div
  data-wp-interactive="myPlugin"
  <?php echo wp_interactivity_data_wp_context( $context ); ?>
>
  <button data-wp-on-async--click="actions.toggle">
    Toggle
  </button>
  <div data-wp-bind--hidden="!context.isOpen">
    Content for <?php echo esc_html( $context['itemName'] ); ?>
  </div>
</div>

Derived State on the Server

When derived state affects the initial HTML, define it in PHP to avoid layout shifts.

Static Derived State

When the derived value is known at render time:

$fruits    = array( 'Apple', 'Banana', 'Cherry' );
$hasFruits = count( $fruits ) > 0;

wp_interactivity_state( 'myPlugin', array(
  'fruits'    => $fruits,
  'hasFruits' => $hasFruits,
));

Dynamic Derived State (using closures)

When the value depends on context (e.g., inside data-wp-each loops):

wp_interactivity_state( 'myPlugin', array(
  'fruits'       => array( 'apple', 'banana', 'cherry' ),
  'shoppingList' => array( 'apple', 'cherry' ),
  'onShoppingList' => function() {
    $state   = wp_interactivity_state();
    $context = wp_interactivity_get_context();
    return in_array( $context['item'], $state['shoppingList'] ) ? 'Yes' : 'No';
  },
));

The closure is evaluated during directive processing for each element.

Complete Example: List with Server Rendering

PHP (render callback or template)

<?php
$fruits = array( 'Apple', 'Banana', 'Cherry' );

wp_interactivity_state( 'myFruitPlugin', array(
  'fruits'    => $fruits,
  'hasFruits' => count( $fruits ) > 0,
  'mango'     => __( 'Mango' ),
));
?>

<div data-wp-interactive="myFruitPlugin">
  <button data-wp-on-async--click="actions.addMango">
    <?php esc_html_e( 'Add Mango' ); ?>
  </button>
  <button data-wp-on-async--click="actions.clearAll">
    <?php esc_html_e( 'Clear All' ); ?>
  </button>

  <ul data-wp-bind--hidden="!state.hasFruits">
    <template data-wp-each="state.fruits">
      <li data-wp-text="context.item"></li>
    </template>
  </ul>

  <p data-wp-bind--hidden="state.hasFruits">
    <?php esc_html_e( 'No fruits available.' ); ?>
  </p>
</div>

JavaScript (view.js)

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

const { state } = store( 'myFruitPlugin', {
  state: {
    get hasFruits() {
      return state.fruits.length > 0;
    },
  },
  actions: {
    addMango() {
      state.fruits.push( state.mango );
    },
    clearAll() {
      state.fruits = [];
    },
  },
});

Rendered Output (initial HTML)

<div data-wp-interactive="myFruitPlugin">
  <button data-wp-on-async--click="actions.addMango">Add Mango</button>
  <button data-wp-on-async--click="actions.clearAll">Clear All</button>

  <ul>
    <li>Apple</li>
    <li>Banana</li>
    <li>Cherry</li>
  </ul>

  <p hidden>No fruits available.</p>
</div>

The hidden attribute is added server-side because state.hasFruits is true.

Serializing Values for Client Use

Use wp_interactivity_state() to pass server values to client JavaScript:

Translations

wp_interactivity_state( 'myPlugin', array(
  'labels' => array(
    'add'    => __( 'Add Item', 'textdomain' ),
    'remove' => __( 'Remove Item', 'textdomain' ),
    'empty'  => __( 'No items found', 'textdomain' ),
  ),
));

Ajax URLs and Nonces

wp_interactivity_state( 'myPlugin', array(
  'ajaxUrl' => admin_url( 'admin-ajax.php' ),
  'nonce'   => wp_create_nonce( 'myPlugin_nonce' ),
  'restUrl' => rest_url( 'myPlugin/v1/' ),
));

Client Usage

const { state } = store( 'myPlugin', {
  actions: {
    *fetchData() {
      const formData = new FormData();
      formData.append( 'action', 'my_action' );
      formData.append( '_ajax_nonce', state.nonce );

      const response = yield fetch( state.ajaxUrl, {
        method: 'POST',
        body: formData,
      });
      return yield response.json();
    },
  },
});

Themes and Plugins without block.json

For themes or plugins not using block.json, use wp_interactivity_process_directives():

<?php
wp_interactivity_state( 'myTheme', array(
  'menuOpen' => false,
));

ob_start();
?>

<nav
  data-wp-interactive="myTheme"
  data-wp-class--is-open="state.menuOpen"
>
  <button data-wp-on-async--click="actions.toggleMenu">
    Menu
  </button>
  <ul data-wp-bind--hidden="!state.menuOpen">
    <li><a href="/">Home</a></li>
    <li><a href="/about">About</a></li>
  </ul>
</nav>

<?php
$html = ob_get_clean();
echo wp_interactivity_process_directives( $html );

Only call wp_interactivity_process_directives() once at the outermost template level.

PHP Helper Functions Reference

Common Pitfalls

Server Directive Processing Not Enabled

For `block.json` users: Without supports.interactivity, directives are not processed:

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

For themes/plugins: Ensure wp_interactivity_process_directives() is called on the HTML output.

Derived State Missing on Server

If state.hasFruits is only defined in JavaScript, the hidden attribute won't be set:

<!-- Without server state: shows briefly then hides (layout shift) -->
<p data-wp-bind--hidden="state.hasFruits">No fruits</p>

State Not Matching Client Expectations

Ensure PHP and JavaScript derived state logic matches:

// PHP
'hasFruits' => count( $fruits ) > 0,

// JavaScript - must match PHP logic
get hasFruits() {
  return state.fruits.length > 0;
}

External References

• WordPress: Server-side rendering
• WordPress: Understanding global state, local context and derived state
• WordPress: Interactivity API Reference