| name | wp-interactivity-api |
| description | Use only when the task explicitly involves WordPress Interactivity API, @wordpress/interactivity, data-wp-* directives, block/template reactivity, or admin/plugin UI that must run inside WordPress rather than the React SPA. |
| risk | low |
| source | https://github.com/WordPress/agent-skills |
| date_added | 2026-03-05 |
| updated | 2026-05-30 |
| compatibility | Targets WordPress 6.9+ and PHP 8.3+ for this project. |
WP Interactivity API — djzeneyer.com
Status in this project
This is a rare/conditional skill. The main public frontend is a React SPA, not WordPress block interactivity. Do not introduce the WordPress Interactivity API just because a UI needs state.
Use this skill only when the interaction must live inside WordPress-rendered markup, a plugin admin screen, a block/template surface, or another context where the React SPA is not the owner.
When to use
Use this skill when the task involves:
@wordpress/interactivity.data-wp-interactive or other data-wp-* directives.- Reactive behavior inside WordPress blocks/templates.
- Plugin/admin UI that should not become part of the React SPA.
- Interactive GamiPress/admin elements rendered by WordPress/PHP.
Do not use it for normal React pages/components. Use react-patterns or react-best-practices instead.
Inputs required
- Plugin/theme surface affected.
- Whether markup is server-rendered by PHP/blocks.
- Interaction goal.
- Whether a build step already exists.
- Privacy/security boundary of the state being rendered.
Procedure
1) Detect existing usage
Search for:
data-wp-interactive.@wordpress/interactivity.viewScriptModule in block.json.wp_interactivity_state.wp_interactivity_data_wp_context.
2) Confirm ownership
Ask:
- Is this inside WordPress/PHP/admin/block land?
- Would the React SPA be a better owner?
- Does this require server-rendered initial HTML to avoid CLS?
- Is any state private/user-specific?
3) Server-render first
Prefer server-rendered HTML and PHP-initialized state to avoid layout shifts.
wp_interactivity_state('zenGame', [
'points' => 150,
'rank' => 'Silver',
]);
$context = ['isOpen' => false];
?>
<div <?php echo wp_interactivity_data_wp_context($context); ?>>
...
</div>
<?php
Escape output and protect private user data as usual.
4) Implement directives safely
- Use
data-wp-on--click, data-wp-bind--*, data-wp-text, etc.
- Avoid deprecated directives for the target WP version.
- Keep store names unique, e.g.
zenGame, zenAdmin, zenBit.
- Avoid mixing multiple plugin stores on the same element without clear ownership.
5) Build/tooling
The project plugins do not generally rely on @wordpress/scripts for bundling. If adding Interactivity API usage requires a build step, confirm the tradeoff before introducing new tooling.
Verification
- Directives are present in server-rendered HTML.
- No layout shift during hydration.
- State updates correctly.
- No browser console errors.
- Private data is not printed into public HTML.
wp_interactivity_process_directives() is used if needed for custom markup outside blocks.
Failure modes
- Directives do not fire because
data-wp-interactive parent is missing/wrong.
- Hydration mismatch between PHP and JS initial state.
- Script module enqueue/build missing.
- React SPA and WP Interactivity both try to own the same UI.
- Private user state leaked into public cached HTML.
Escalation
Consult the official WordPress Interactivity API docs and wp-plugin-development before adding new build tooling or plugin architecture.
