skilld
All skills
automattic avatar

/wp-interactivity-api

@0ddab58 official
by automatticautomattic/agent-skills211 stars
37

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.

Ask your Agent

Use this Skill: https://skilld.dev/gh/automattic/agent-skills/wp-interactivity-api

This session only. Nothing lands on disk.

referencesdebugging.md

≈343 tokens on demand. Your agent reads this file only when SKILL.md points to it.

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.

Source: SKILL.md on GitHub

Third-party checks

No alerts17d4 checks · Risk SAFE
  • Gen Agent Trust Hub17d

    This skill provides technical documentation and procedures for working with the WordPress Interactivity API. It is authored by a trusted vendor (Automattic) and follows standard WordPress security best practices, such as the use of nonces and server-side state initialization. No malicious patterns or security risks were identified.

  • Socket17d

    No alerts

  • Snyk17d

    Risk: LOW · No issues

  • Runlayer6mo

    1/4 files flagged

Provenance

Signed by skilld at 0ddab58. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 5 months ago.

Dormantupdated 9 months ago

Capability

Other metadata
compatibility
Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI.

Topics

  • wordpress
  • interactivity-api
  • data-wp-directives
  • javascript
  • php
  • hydration
  • block-development
  • state-management
  • server-rendering

README badge

README badge for automattic/agent-skills/wp-interactivity-api

What it does

Builds and debugs WordPress Interactivity API features using data-wp-* directives, the @wordpress/interactivity store, and block viewScriptModule integration. Covers server-side rendering, state initialization via wp_interactivity_state(), and common hydration issues in WordPress 6.9+.

Generated from the current SKILL.md.

Frequently asked

Does this skill work with WordPress versions below 6.9?
The skill targets WordPress 6.9+. Older versions do not have full Interactivity API support and will not work with this skill's workflows.
What if my project uses a custom bundler instead of @wordpress/scripts?
The skill can work with custom bundlers (webpack/vite), but you must confirm the repo's build output supports module output and module loading. Ask the user or inspect the build config if it's unclear.
How do I prevent layout shift when the client-side JavaScript loads?
Pre-render the initial state on the server using `wp_interactivity_state()` and `wp_interactivity_data_wp_context()` in PHP, and replicate derived state logic in PHP so directives like `data-wp-bind--hidden` render correctly before hydration.
What changed in WordPress 6.9 regarding directives?
`data-wp-ignore` is now deprecated and breaks context inheritance. The skill also supports unique directive IDs using the `---` separator to attach multiple directives of the same type to one element (e.g., `data-wp-on--click---plugin-a` and `data-wp-on--click---plugin-b`).
How do I debug when directives are present but nothing happens on interaction?
Verify the viewScriptModule is enqueued, the DOM element has `data-wp-interactive`, the store namespace matches the directive value, and check for JavaScript errors before hydration. Consult the bundled debugging guide for detailed steps.

Generated from the current SKILL.md. These answers refresh after source changes.