Wp Interactivity API

1---
2name: wp-interactivity-api
3description: "Use when building or debugging WordPress Interactivity API features (data-wp-* directives, @wordpress/interactivity store/state/actions, block viewScriptModule integration, wp_interactivity_*()) including performance, hydration, and directive behavior."
4compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
5---
6 
7# WP Interactivity API
8 
9## When to use
10 
11Use this skill when the user mentions:
12 
13- Interactivity API, `@wordpress/interactivity`,
14- `data-wp-interactive`, `data-wp-on--*`, `data-wp-bind--*`, `data-wp-context`,
15- block `viewScriptModule` / module-based view scripts,
16- hydration issues or “directives don’t fire”.
17 
18## Inputs required
19 
20- Repo root + triage output (`wp-project-triage`).
21- Which block/theme/plugin surfaces are affected (frontend, editor, both).
22- Any constraints: WP version, whether modules are supported in the build.
23 
24## Procedure
25 
26### 1) Detect existing usage + integration style
27 
28Search for:
29 
30- `data-wp-interactive`
31- `@wordpress/interactivity`
32- `viewScriptModule`
33 
34Decide:
35 
36- Is this a block providing interactivity via `block.json` view script module?
37- Is this theme-level interactivity?
38- Is this plugin-side “enhance existing markup” usage?
39 
40If you’re creating a new interactive block (not just debugging), prefer the official scaffold template:
41 
42- `@wordpress/create-block-interactive-template` (via `@wordpress/create-block`)
43 
44### 2) Identify the store(s)
45 
46Locate store definitions and confirm:
47 
48- state shape,
49- actions (mutations),
50- callbacks/event handlers used by `data-wp-on--*`.
51 
52### 3) Server-side rendering (best practice)
53 
54**Pre-render HTML on the server** before outputting to ensure:
55 
56- Correct initial state in the HTML before JavaScript loads (no layout shift).
57- SEO benefits and faster perceived load time.
58- Seamless hydration when the client-side JavaScript takes over.
59 
60#### Enable server directive processing
61 
62For components using `block.json`, add `supports.interactivity`:
63 
64```json
65{
66  "supports": {
67    "interactivity": true
68  }
69}
70```
71 
72For themes/plugins without `block.json`, use `wp_interactivity_process_directives()` to process directives.
73 
74#### Initialize state/context in PHP
75 
76Use `wp_interactivity_state()` to define initial global state:
77 
78```php
79wp_interactivity_state( 'myPlugin', array(
80  'items'    => array( 'Apple', 'Banana', 'Cherry' ),
81  'hasItems' => true,
82));
83```
84 
85For local context, use `wp_interactivity_data_wp_context()`:
86 
87```php
88<?php
89$context = array( 'isOpen' => false );
90?>
91<div <?php echo wp_interactivity_data_wp_context( $context ); ?>>
92  ...
93</div>
94```
95 
96#### Define derived state in PHP
97 
98When derived state affects initial HTML rendering, replicate the logic in PHP:
99 
100```php
101wp_interactivity_state( 'myPlugin', array(
102  'items'    => array( 'Apple', 'Banana' ),
103  'hasItems' => function() {
104    $state = wp_interactivity_state();
105    return count( $state['items'] ) > 0;
106  }
107));
108```
109 
110This ensures directives like `data-wp-bind--hidden="!state.hasItems"` render correctly on first load.
111 
112For detailed examples and patterns, see `references/server-side-rendering.md`.
113 
114### 4) Implement or change directives safely
115 
116When touching markup directives:
117 
118- keep directive usage minimal and scoped,
119- prefer stable data attributes that map clearly to store state,
120- ensure server-rendered markup + client hydration align.
121 
122**WordPress 6.9 changes:**
123 
124- **`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.
125- **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="..."`).
126- **New TypeScript types**: `AsyncAction<ReturnType>` and `TypeYield<T>` help with async action typing.
127 
128For quick directive reminders, see `references/directives-quickref.md`.
129 
130### 5) Build/tooling alignment
131 
132Verify the repo supports the required module build path:
133 
134- if it uses `@wordpress/scripts`, prefer its conventions.
135- if it uses custom bundling, confirm module output is supported.
136 
137### 6) Debug common failure modes
138 
139If “nothing happens” on interaction:
140 
141- confirm the `viewScriptModule` is enqueued/loaded,
142- confirm the DOM element has `data-wp-interactive`,
143- confirm the store namespace matches the directive’s value,
144- confirm there are no JS errors before hydration.
145 
146See `references/debugging.md`.
147 
148## Verification
149 
150- `wp-project-triage` indicates `signals.usesInteractivityApi: true` after your change (if applicable).
151- Manual smoke test: directive triggers and state updates as expected.
152- If tests exist: add/extend Playwright E2E around the interaction path.
153 
154## Failure modes / debugging
155 
156- Directives present but inert:
157  - view script not loading, wrong module entrypoint, or missing `data-wp-interactive`.
158- Hydration mismatch / flicker:
159  - server markup differs from client expectations; simplify or align initial state.
160  - derived state not defined in PHP: use `wp_interactivity_state()` with closures.
161- Initial content missing or wrong:
162  - `supports.interactivity` not set in `block.json` (for blocks).
163  - `wp_interactivity_process_directives()` not called (for themes/plugins).
164  - state/context not initialized in PHP before render.
165- Layout shift on load:
166  - derived state like `state.hasItems` missing on server, causing `hidden` attribute to be absent.
167- Performance regressions:
168  - overly broad interactive roots; scope interactivity to smaller subtrees.
169- Client-side navigation issues (WordPress 6.9):
170  - `getServerState()` and `getServerContext()` now reset between page transitions—ensure your code doesn't assume stale values persist.
171  - Router regions now support `attachTo` for rendering overlays (modals, pop-ups) dynamically.
172 
173## Escalation
174 
175- If repo build constraints are unclear, ask: "Is this using `@wordpress/scripts` or a custom bundler (webpack/vite)?"
176- Consult:
177  - `references/server-side-rendering.md`
178  - `references/directives-quickref.md`
179  - `references/debugging.md`
180